Committing code

这个部分是针对提交者和任何有兴趣知道代码如何提交到Django的人。 如果您是想向Django提供代码的社区成员，请查看Working with Git and GitHub。

Handling pull requests

由于Django现在托管在GitHub，大多数补丁都是以拉请求的形式提供的。

当提交拉取请求时，请确保每个单独的提交符合下面描述的提交指南。 贡献者应该提供尽可能最好的请求。 然而，在实践中，提交者（可能更熟悉提交指南）可能决定将提交提交给标准本身。

注

在合并之前，但是在审查之后，通过在PR上评论“buildbot，测试这个请求”来让Jenkins测试pull请求。 有关详细信息，请参阅我们的Jenkins wiki页面。

在本地检查拉取请求的简单方法是在~/.gitconfig中添加一个别名（upstream假定为django/django ）：

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

现在，您可以简单地运行git pr ####来检出相应的pull请求。

此时，您可以处理代码。 使用git rebase -i和git commit - 修改以确保提交的质量达到预期水平。 准备好后：

$ # Pull in the latest changes from master.
$ git checkout master
$ git pull upstream master
$ # Rebase the pull request on master.
$ git checkout pr/####
$ git rebase master
$ git checkout master
$ # Merge the work as "fast-forward" to master to avoid a merge commit.
$ # (in practice, you can omit "--ff-only" since you just rebased)
$ git merge --ff-only pr/XXXX
$ # If you're not sure if you did things correctly, check that only the
$ # changes you expect will be pushed to upstream.
$ git push --dry-run upstream master
$ # Push!
$ git push upstream master
$ # Delete the pull request branch.
$ git branch -d pr/xxxx

对于您自己的分支机构进行更改，在重新掌握主控后，在合并并推送到上游之前强制推送到您的叉子。 这允许主服务器和您的分支机构上的提交哈希值匹配，自动关闭拉取请求。 由于您不能推送到其他贡献者的分支，请在合并之后评论“合并于XXXXXXX”（替换为提交哈希）。 Trac检查此消息格式，以在票证页面上指示是否合并了拉取请求。

如果拉动请求不需要合并为多个提交，则可以在网站上使用GitHub的“壁球和合并”按钮。 根据the guidelines编辑提交消息，并删除自动附加到消息第一行的拉取请求号。

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

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

实用性击败纯度，所以由每个提交者决定多少历史记录为拉取请求做。 主要的是参与社区，完成工作，并有一个可用的提交历史。

Committing guidelines

此外，当将代码提交到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为补丁，C为审查。

  • 对于提交到分支，在提交消息前面加上分支名称。 例如：“[1.4.x]修正#xxxxx - 增加了对心智阅读的支持。

  • 限制提交到最细粒度的变化是有意义的。 这意味着，使用频繁的小提交，而不是很少的大提交。 例如，如果实现要素X需要对库Y进行小的更改，请先将更改提交到库Y，然后在单独的提交中提交要素X. 这使得长途帮助大家遵循您的更改。

  • 从功能更改中分离错误修复。 根据backwards-compatibility policy，修补程序可能需要反向运行到稳定分支。

  • 如果您的提交在Django 票证跟踪器中关闭票证，请使用文本“Fixed #xxxxx”开始提交消息，其中“xxxxx”是您提交修复的票证号。 示例：“固定＃123 - 添加了whizbang功能。 我们绑定了Trac，以便任何提交消息的格式将自动关闭引用的票证，并与完整的提交消息发表评论。

    如果您的提交关闭了票证并且在分支中，请先使用分支名称，然后使用“Fixed #xxxxx”。例如：“[1.4.x] Fixed＃123 - Added whizbang feature。

    对于好奇，我们使用了Trac插件。

注

请注意，Trac集成不知道任何关于pull请求。 因此，如果您尝试在提交消息中使用短语“closing＃400”关闭拉取请求，GitHub将关闭拉取请求，但Trac插件也将关闭Trac中相同编号的票证。

  • 如果您的提交在Django 票据跟踪器中引用票证，但不关闭票证，请添加短语“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 master.

    维基上有一个脚本来自动化。

Reverting commits

没有人是完美的；将犯下错误。

但要尽量确保错误不会发生。 只是因为我们有一个回归政策不放松你的责任，以尽可能最高的质量为目标。 真的：仔细检查你的工作，或者在另一个提交者之前检查你的工作，之前提交它！

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

  • 如果可能，让原始作者恢复自己的提交。
  • 未经原作者许可，不得复原其他作者的更改。
  • 使用git revert - 这将使一个反向提交，但原始提交仍将是提交历史的一部分。
  • 如果原始作者无法达到（合理的时间 - 一天左右），问题严重 - 崩溃，重大测试失败等。 - 然后在django-developers邮件列表中请求反对，然后如果没有，则返回。
  • 如果问题很小（功能冻结后的功能提交，说），等待它。
  • 如果提交者和回复者之间存在不一致，请尝试在django-developers邮件列表上进行操作。 如果不能达成协议，则应将其付诸表决。
  • 如果提交引入了一个确认的，公开的安全漏洞，那么提交可能会立即恢复，没有任何人的许可。
  • 如果提交中断了发布分支，则发布分支维护者可以无需许可地将提交回退到发布分支。
  • 如果您错误地将主题分支推送到django/django，只需删除它。 例如，如果你做的是：git push 上游 feature_antigravity反向推送：git push 上游 ：feature_antigravity。