提交代码 — Django 文档

提交代码

本节面向提交者和任何有兴趣了解代码如何提交到 Django 的人。 如果您是想要为 Django 贡献代码的社区成员，请查看 Working with Git and GitHub。

处理拉取请求

由于 Django 托管在 GitHub 上，因此补丁以拉取请求的形式提供。

提交拉取请求时，请确保每个单独的提交都符合下面描述的提交指南。 贡献者应尽可能提供最好的拉取请求。 然而，在实践中，提交者 - 他们可能更熟悉提交指南 - 可能会决定自己使提交达到标准。

您可能希望让 Jenkins 使用一种不会自动运行的拉取请求构建器（例如 Oracle 或 Selenium）来测试拉取请求。 有关说明，请参阅 Jenkins wiki 页面 。

如果你发现自己更频繁地在本地检查拉取请求，这个 git 别名会很有帮助：

[alias]
    pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"

将其添加到您的 ~/.gitconfig，并将 upstream 设置为 django/django。 然后你可以运行 git pr #### 来检查相应的拉取请求。

此时，您可以处理代码。 使用 git rebase -i 和 git commit --amend 来确保提交具有预期的质量水平。 一旦你准备好了：

在重新基于 main 之后但在合并和推送到上游之前强制推送到分支。 这允许主和分支上的提交哈希匹配，从而自动关闭拉取请求。

如果一个 pull request 不需要被合并为多个提交，你可以使用 GitHub 网站上的“Squash and merge”按钮。 根据需要编辑提交消息以符合 准则 并删除自动附加到消息第一行的拉取请求编号。

重写拉取请求的提交历史时，目标是使 Django 的提交历史尽可能可用：

• 如果补丁包含来回提交，则将它们重写为一个。 例如，如果一次提交添加了一些代码，而第二次提交修复了第一次提交中引入的风格问题，则这些提交应在合并之前被压缩。
• 通过逻辑分组分离对不同提交的更改：如果您在对文件进行其他更改的同时进行样式清理，将更改分成两个不同的提交将使查看历史更容易。
• 注意拉取请求中上游分支的合并。
• 测试应该通过并且文档应该在每次提交后构建。 测试和文档都不应该发出警告。
• 琐碎的小补丁通常最好在一次提交中完成。 如果有意义的话，中到大型的工作可能会被分成多个提交。

实用性胜过纯度，因此由每个提交者决定为拉取请求做多少历史修改。 要点是让社区参与进来，完成工作，并拥有可用的提交历史。

提交指南

此外，在向 Django 的 Git 存储库提交代码时，请遵循以下准则：

• 切勿强行更改 django/django 分支的已发布历史记录。 如果您绝对必须（例如出于安全原因），请首先与团队讨论情况。

• 对于任何中到大的更改，其中“中到大”是根据您的判断，请在更改前在 django-developers 邮件列表中提出。

  如果你在 django-developers 上提出了一些东西，但没有人回应，请不要认为你的想法很棒，应该立即实施，因为没有人提出异议。 每个人并不总是有很多时间立即阅读邮件列表讨论，因此您可能需要等待几天才能得到回复。

• 用过去时写详细的提交消息，而不是现在时。

  • 好：“修复了 RSS API 中的 Unicode 错误。”

  • 不好的：“修复了 RSS API 中的 Unicode 错误。”

  • 不好的：“修复 RSS API 中的 Unicode 错误。”

  提交消息最多应为 72 个字符的行。 应该有一个主题行，由一个空行分隔，然后是 72 个字符行的段落。 限制是软的。 对于主题行，越短越好。 在提交消息的正文中，更多的细节总比更少的好：

  Fixed #18307 -- Added git workflow guidelines.
  
  Refactored the Django's documentation to remove mentions of SVN
  specific tasks. Added guidelines of how to use Git, GitHub, and
  how to use pull request together with Trac instead.

  在提交消息中感谢贡献者：“感谢 A 的报告和 B 的审查。” 根据需要使用 git 的 Co-Authored-By。

• 对于对分支的提交，在提交消息前加上分支名称。 例如：“[1.4.x] Fixed #xxxxx – 添加了对读心术的支持。”

• 将提交限制为有意义的最细粒度的更改。 这意味着，使用频繁的小提交而不是不频繁的大提交。 例如，如果实现功能 X 需要对库 Y 进行小的更改，则首先将更改提交到库 Y，然后在单独的提交中提交功能 X。 这在帮助每个人遵循您的更改方面大有 长路 。

• 将错误修复与功能更改分开。 根据 支持的版本 ，错误修正可能需要向后移植到稳定分支。

• 如果您的提交在 Django ticket tracker 中关闭了一个票证，请以文本“Fixed #xxxxx”开始您的提交消息，其中“xxxxx”是您提交修复的票证编号。 示例：“固定 #123 – 添加了 whizbang 功能。”。 我们已经操纵了 Trac，以便该格式的任何提交消息将自动关闭引用的票证，并使用完整的提交消息向其发布评论。

  出于好奇，我们为此使用了 Trac 插件 。

笔记

请注意，Trac 集成对拉取请求一无所知。 因此，如果您尝试在提交消息中关闭带有短语“closes #400”的拉取请求，GitHub 将关闭拉取请求，但 Trac 插件不会关闭 Trac 中相同编号的票证。

• 如果您的提交引用了 Django ticket tracker 中的票证，但 没有 关闭票证，请包含短语“Refs #xxxxx”，其中“xxxxx”是您的票证编号提交参考。 这将自动对相应的工单发表评论。

• 使用此模式为向后移植编写提交消息：

  [<Django version>] Fixed <ticket> -- <description>
  
  Backport of <revision> from <branch>.

  例如：

  [1.3.x] Fixed #17028 -- Changed diveintopython.org -> diveintopython.net.
  
  Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.

  wiki 上有一个 脚本可以自动执行此操作。

  如果提交修复了回归，请将其包含在提交消息中：

  Regression in 6ecccad711b52f9273b1acb07a57d3f806e93928.

  （使用引入回归的提交哈希）。

恢复提交

没有人是完美的; 会犯错误。

但是要非常努力地确保不会发生错误。 仅仅因为我们有退货政策并不能减轻您追求最高质量的责任。 真的：仔细检查你的工作，或者让另一个提交者检查它，在你首先提交它之前！

当发现错误提交时，请遵循以下准则：

• 如果可能，让原作者恢复他们自己的提交。
• 未经原作者许可，请勿还原其他作者的更改。
• 使用 git revert - 这将进行反向提交，但原始提交仍将是提交历史的一部分。
• 如果无法联系到原作者（在合理的时间内 - 一天左右）并且问题很严重 - 崩溃错误，重大测试失败等。 – 然后在 django-developers 邮件列表上提出反对意见，如果没有，则回复。
• 如果问题很小（比如功能冻结后的功能提交），请等待。
• 如果提交者和未来的回复者之间存在分歧，请尝试在 django-developers 邮件列表中解决。 如果无法达成协议，则应将其付诸表决。
• 如果提交引入了已确认的、已公开的安全漏洞，则该提交可能会在未经任何人许可的情况下立即恢复。
• 如果提交破坏了发布分支，发布分支维护者可以在未经许可的情况下撤回对发布分支的提交。
• 如果您错误地将主题分支推送到 django/django，请将其删除。 例如，如果你做了：git push upstream feature_antigravity，做一个反向推送：git push upstream :feature_antigravity。