在 pymc-examples 上审查 PR#

本页的目标受众是 pymc-examples 仓库的 PR 评审者。它主要收集了来自其 贡献指南、PR 模板 和 Jupyter 风格指南 页面的资源，以集中所有评审者的资源，并特别强调评审者的任务和职责。

重要

最重要的指导方针如下：当你对某事不完全确定时，沟通它，四处询问并（重新）阅读文档。

pymc-examples 是一个包含大量笔记本的集合，涵盖了PyMC和贝叶斯统计的许多领域和应用。此外，其HTML生成基础设施得到了专业人士的改进，这些人也得到了报酬，以便他们能够全身心投入这项任务。即使你对这个主题不了解，对所使用的科技栈不熟悉，或者对这两者都不确定，这也没有关系。你仍然可以进行评审，无论是专注于你的专业领域，还是花一些时间浏览所有可用的资源来学习你不确定的部分。

1. Define the scope#

在开始之前，你需要确保你理解了PR的范围，并设定你自己的审查范围。如果从PR描述中无法清楚地了解范围，请要求作者更新它！

有许多有效的贡献可以对 pymc-examples 中的笔记本进行。它们可以集中在代码、样式、措辞等方面… pymc-examples 需要定期更新，而且在许多情况下，这些更新是否是部分的，并不更新笔记本中所有可以更新的内容，这并不重要。

虽然并非所有部分更新都是有效或有帮助的。例如，如果对代码进行更新，大部分文字可能不需要更改，但可能会有一些部分专门解释所使用的代码。我们不知道下一次部分更新何时到来，因此PR应合并工作且连贯的笔记本。如果代码更新为使用 Potential 而不是 DensityDist，并且解释中提到了 DensityDist，那么该特定句子也需要更新。

旨在更新笔记本所有内容的PR可能需要3个或更多的审阅者，每个审阅者负责示例的不同方面，如PyTensor的使用、概念的撰写和解释、ArviZ的使用、使用MyST+Sphinx的样式设计，或笔记本的结构和范围。

除非你计划审查所有内容，否则在开始审查时提及你的审查涵盖（或跳过）的内容。

部分工作还包括确保PR描述链接到相关的问题。

2. Try to be concise and clear#

在评论时尽量简洁明了。确保留下可操作的反馈。 这样你花在评审上的时间会更少，PR 作者花在查看评审上的时间也会更少。以下是一些关于这方面的例子：

  • 在开始审查之前，先从头到尾浏览一遍笔记本。这样可以防止你在发现内容并非缺失而是结构混乱之前，花费时间撰写关于缺失内容的评论并建议如何添加。

  • 在你确定不需要进行大幅重写之前，不要校对文本。当整个段落都要重写时，校对/修正一个错字有什么意义呢？

  • 在你的评论中包含一些理由。贡献者来自不同的地方、领域和个人背景，英语可能不是他们的（也不是你的）第一语言。添加建议背后的原因有助于确保建议清晰，并增加作者不再重复这种模式的可能性。

而不是意味着：

  • 避免提及PR中的好事或不感谢PR作者。

  • 晦涩难懂或写作不佳

3. Review the code and supporting text#

  • 检查笔记本的预期水平，无论是代码还是文本。即，初级笔记本应为了清晰性而牺牲性能，甚至不需要解释，中级和高级笔记本则不应如此。

  • 然而，在所有情况下，请记住这段代码是为了阅读而写的！晦涩的一行代码几乎没有什么好处，而在中级或高级笔记本中却有很多损失。如果某些代码是必要的但不太相关，并且你认为占用了太多空间，请将该单元格/输入/输出隐藏在切换按钮下。

  • 确保文本内容相关，必要时解释代码块，并与代码保持同步。

  • 在 ReviewNB 上检查差异和输出

4. Review the styling and formatting#

  • 忽略 ReviewNB。当存在涉及格式的差异时，ReviewNB 会错误地渲染笔记本，它可能会在渲染视图中添加不存在的 HTML 标签，搞乱链接……此外，我们不希望单独渲染笔记本，而是作为示例画廊中的一个页面。

  • 检查 readthedocs 预览并使用 MyST 笔记本格式查看原始文本差异，并在涉及格式时进行评论。

  • 通常检查是否遵循了 Jupyter 风格指南 中描述的风格。

目前（在我们用v4重新运行笔记本并更新文档到新格式期间），请确保以下所有内容：

  • 没有指向 PyMC/ArviZ/PyTensor 文档的 URL。

  • 笔记本顶部有一个 post 指令和 MyST 目标。

  • 笔记本正在被 pre-commit 检查（它不应出现在 .pre-commit-config.yaml 的任何排除部分）

  • 无水印（这已经是CI中断的，但仍包含在此处以提供完整上下文）

它们非常具体，即使最初PR作者没有打算，也应该成为PR范围的一部分。可以把这看作是CI中断。

5. Check CI#

  • 在 pymc-examples 中的 CI 非常具体，并且从未出现过误报。

  • 然而，它的作用是跳过某些文件的检查！在审查时，请确保文件未被CI排除。

检查清单#

这可能会被移动到一个由机器人添加到每个新PR的评论中，参见 pymc-examples#288

  • 检查PR描述的清晰度和相关问题的链接

  • 定义审查范围

  • 留下有行动依据的评论

  • 在 ReviewNB 中检查代码、输出和支持文本

  • 在readthedocs预览和MyST笔记本表示中检查样式和渲染

  • 检查是否存在：

    • 无 指向 PyMC/PyTensor/ArviZ 文档的 URL

    • 带有标签和类别的帖子指令以及笔记本顶部的 MyST 目标

    • 在笔记本底部添加一个包含所有相关库的水印，以确保可重复性

  • 检查CI是否通过，并且笔记本正在被pre-commit检查

  • 校对更改（一旦不需要重大重写）