核心开发者指南#

作为核心开发者，您应该按照贡献者指南的要求继续提交拉取请求。您有责任引导其他贡献者完成审查流程。您应该熟悉我们的使命与价值观。您也有权合并或批准其他贡献者的拉取请求。这就像核弹发射密码一样，是一种共享的权力：您只能在另一位核心开发者批准拉取请求并且您自己仔细审查后才能合并。（参见下面的审查，特别是只合并您理解的更改。）为确保整洁的 Git 历史记录，除非有充分理由，请使用 GitHub 的壁球式合并 (Squash and Merge) 功能进行合并。

审查#

如何进行良好的审查#

永远对贡献者友善。NetworkX 几乎所有的工作都是志愿完成的，我们对此深表感激。对想法和实现提供建设性的批评，并回想自己新手时期工作受到评价时的感受。

NetworkX 非常重视代码审查中的指导作用。新用户通常需要更多的帮助，因为他们可能几乎没有 Git 经验。请不厌其烦地重复说明，如果您不认识某位贡献者，请将他们引导至我们的开发指南或网络上的其他 GitHub 工作流程教程。不要假定他们了解 GitHub 的工作方式（例如，许多人不知道添加提交会自动更新拉取请求）。温和、礼貌、友善的鼓励可以决定一位新贡献者能否成为核心开发者，或一个拉取请求是否被放弃。

审查时，重点关注以下几点：

  1. API：API 是用户首次使用 NetworkX 时看到的东西。API 一旦发布就难以更改，因此应该简单、函数式（即不携带状态）、与库的其他部分保持一致，并应避免修改输入变量。请熟悉项目的弃用政策。

  2. 文档：任何新功能都应该有一个图库示例，不仅演示其用法，还要进行解释。

  3. 算法：在批准代码修改或新增之前，您应该理解其内容。（参见下面的只合并您理解的更改。）实现应该与其声称的功能一致，并且应简单、易读且高效。

  4. 测试：对库的所有贡献必须经过测试，并且每条新增的代码行应至少被一个测试覆盖。好的测试不仅执行代码，还会探索边界情况。不审查测试是很诱人的，但请务必这样做。

其他更改可能只是琐碎的细节：拼写错误、格式等。不要要求贡献者进行这些更改，而是通过推送到他们的分支或使用 GitHub 的建议功能来完成。（后者更可取，因为它让贡献者可以选择是否接受更改。）

我们的默认合并策略是将所有 PR 提交压扁成一个提交。希望将 main 分支的最新更改合并到自己分支的用户，应建议他们使用合并 (merge)，而不是变基 (rebase)。即使出现合并冲突，除非您确定贡献者熟悉 Git，否则不要要求变基。相反，请您自己变基该分支，强制推送到他们的分支，并指导贡献者如何强制拉取 (force-pull)。如果贡献者不再活跃，您可以通过提交新的拉取请求并关闭原始请求来接管他们的分支。在这样做时，请务必说明您并没有抛弃贡献者的工作！您应该在提交信息中使用 GitHub 的 Co-authored-by: 关键词来注明原贡献者。

在推送新的更改后，请在拉取请求中添加备注；GitHub 可能不会发送这些更改的通知。

只合并您理解的更改#

长期可维护性是一个重要的考量。代码不仅必须能正常工作，还应该能被多个核心开发者所理解。将来需要进行更改，而原始贡献者可能已经离开了。

因此，除非您理解代码更改，否则不要合并它。请随意寻求帮助：我们长期以来一直向社区成员甚至外部开发者咨询，以在需要时获得更多见解，并将其视为一个极好的学习机会。

虽然我们集体“拥有”成为代码库一部分的任何补丁（和错误！），但您合并的更改由您担保。请认真对待这项责任。

关闭问题和拉取请求#

有时，一个问题可能需要被关闭，即使它没有完全解决。原因可能有很多，例如：

  • 原始发布者未回复澄清请求，且核心开发者均未能重现其问题；

  • 修复该问题很困难，并且它被认为过于小众，不值得投入持续精力或优先于其他问题；或者

  • 核心开发者认为该用例或功能请求不适合包含在 NetworkX 中，

等等。类似地，拉取请求有时需要在不合并的情况下关闭，因为：

  • 该拉取请求实现了一个小众功能，我们认为不值得增加额外的维护负担；

  • 该拉取请求实现了一个有用功能，但需要大量工作才能达到 NetworkX 的标准，而原始贡献者已经离开，也找不到其他开发者进行必要的更改；或者

  • 该拉取请求进行的更改不符合我们的价值观，例如为了实现微小的速度提升而显著增加函数的代码复杂度，

等等。

所有这些都可能是关闭的有效原因，但我们必须注意，不要在没有解释的情况下关闭问题或拉取请求，以免疏远贡献者。关闭时，您的消息应包含：

  • 清楚地解释做出关闭决定的过程。当决定是在社区会议中做出的，而会议记录不像问题本身的评论区那样公开可见时，这一点尤为重要；

  • 感谢贡献者的工作；以及

  • 提供清晰的途径供贡献者或任何人对该决定提出申诉。

这些要点有助于确保所有贡献者都感到受欢迎，并有信心继续贡献，无论过去的贡献结果如何。

更多资源#

作为核心成员，您应该熟悉社区和开发者资源，例如：

您无需监控所有这些社交资源。

本页内容