在 pymc-examples 上审核 PR#

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

重要提示

最重要的准则是：当您对某些事情完全不确定时，请沟通、询问和（重新）阅读文档。

pymc-examples 是一个庞大的笔记本集合，涵盖了 PyMC 和贝叶斯统计的许多领域和应用。此外，其 HTML 生成基础设施已由专门的人员改进，他们也因此获得了报酬，以便能够专注于此项任务。不了解主题、不了解正在使用的技术栈或不确定两者中的任何一个都是完全正常的。您仍然可以进行审核，要么专注于您的专业知识，要么花一些时间浏览所有可用的资源，以了解您不确定的部分。

1. 确定范围#

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

可以对 pymc-examples 中的笔记本进行许多有效的贡献。它们可以侧重于代码、样式、措辞…… pymc-examples 需要定期更新，并且在许多情况下，即使这些更新是局部的，并且没有更新笔记本中可以更新的所有内容，也没有关系。

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

旨在更新关于笔记本所有内容的 PR 很容易有 3 个或更多审核人员，每个审核人员涵盖示例的不同方面，例如 PyTensor 用法、概念的编写和解释、ArviZ 用法、使用 MyST+Sphinx 的样式或笔记本的结构和范围。

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

其中一部分还包括确保 PR 描述链接到相关的 issue。

2. 尽量简洁明了#

在您的审核中，尽量做到简洁明了。确保留下可操作的回复。 您将需要更少的时间进行审核，而 PR 作者将需要更少的时间来查看审核。以下是一些关于这样做的好处的示例

  • 在开始审核之前，从上到下略读笔记本。这将防止您花费一些时间来写关于缺少的内容并建议如何添加它，结果却发现它不是缺少，而是结构不良。

  • 在您确定不需要进行大规模重写之前，不要校对文本。当整个段落将被重写时，审阅/修复拼写错误有什么意义呢？

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

以及不意味着

  • 避免提及 PR 中的优点或不感谢 PR 作者。

  • 含糊不清或写得不好

3. 审核代码和支持文本#

  • 检查笔记本的预期水平，包括代码和文本方面。即，初学者笔记本应该为了清晰起见而牺牲性能，甚至不需要解释，中级和高级笔记本则不应该。

  • 然而，在任何情况下，请记住，此代码是为了被阅读而编写的！即使在中级或高级笔记本中，晦涩难懂的单行代码也几乎没有什么好处，反而会损失很多。如果某些代码是必要的但不是很相关，并且您认为占用太多空间，请在切换按钮下隐藏该单元格/输入/输出。

  • 确保文本是相关的，它在需要时解释代码块，并且与代码保持同步。

  • 在 ReviewNB 上检查 diff 和输出

4. 审核样式和格式#

  • 忽略 ReviewNB。当存在涉及格式的 diff 时，ReviewNB 错误地渲染笔记本，它可以将不存在的 HTML 标签添加到渲染视图中，搞乱链接…… 此外，我们不希望单独渲染笔记本，而是将其作为示例库中的页面渲染。

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

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

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

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

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

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

  • 没有水印（这已经是 CI 报错，但仍然包含在此处以提供完整上下文）

它们非常具体，即使 PR 作者最初没有打算，也应该成为 PR 范围的一部分。将其视为 CI 报错。

5. 检查 CI#

  • pymc-examples 中的 CI 非常具体，并且从未发生过误报失败。

  • 然而，它所做的是跳过给定检查中的某些文件！审核时，请务必检查文件是否未从 CI 中排除。

检查清单#

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

  • 检查 PR 描述的清晰度和指向相关 issue 的链接

  • 确定审核范围

  • 留下带有理由的可操作评论

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

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

  • 检查是否存在

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

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

    • 笔记本底部带有所有相关库的水印，以实现可重现性

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

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