Committing code

本节针对Committers和任何有兴趣知道如何将代码提交到Django核心的任何人。如果你是一个社区成员想要贡献代码到Django,请看看Working with Git and GitHub

Handling pull requests

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

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

注意

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

这里有一种方式提交拉请求:

# Create a new branch tracking upstream/master -- upstream is assumed
# to be django/django.
git checkout -b pull_xxxxx upstream/master

# Download the patches from github and apply them.
curl https://github.com/django/django/pull/xxxxx.patch | git am

此时,您可以处理代码。Use git rebase -i and git commit --amend to make sure the commits have the expected level of quality. 准备好后:

# Make sure master is ready to receive changes.
git checkout master
git pull upstream master
# Merge the work as "fast-forward" to master, to avoid a merge commit.
git merge --ff-only pull_xxxxx
# Check that only the changes you expect will be pushed to upstream.
git push --dry-run upstream master
# Push!
git push upstream master

# Get rid of the pull_xxxxx branch.
git branch -d pull_xxxxx

另一种方法是将贡献者的存储库添加为新的远程,检出分支并从那里开始工作:

git remote add <contributor> https://github.com/<contributor>/django.git
git checkout pull_xxxxx <contributor> <contributor's pull request branch>

另一种选择是获取分支而不将贡献者的存储库作为远程添加:

git fetch https://github.com/<contributor>/django.git <contributor's pull request branch>
git checkout -b pull_xxxxx FETCH_HEAD

在这一点上,你可以工作代码,继续如上。

GitHub为pull请求提供一键式合并功能。只有当拉取请求是100%准备就绪,并且您已检查错误(或信任请求制造商足以跳过检查)时,才应使用此选项。目前,无法检查测试是否通过,并且文档无需将更改下载到开发环境即可构建。

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

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

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

Committing guidelines

此外,当将代码提交到Django的Git存储库时,请遵循以下准则:

  • 从不更改django / django分支的发布历史!不要强制将您的更改推送到django / django。如果你绝对必须(出于安全原因)首先与核心团队讨论情况。

  • 对于任何中至大型更改,根据您的判断,“中到大”都要根据django-developers邮寄名单进行更改。

    如果你在django-developers上提出问题,没有人回应,请不要这样说,这意味着你的想法是伟大的,应立即实施,因为没有人反对。Django的核心开发人员没有很多时间来立即阅读邮件列表讨论,因此您可能需要等待几天才能收到回复。

  • 以过去时,不存在时编写详细提交消息。

    • 良好:“修复了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.这在帮助所有Django核心开发人员遵循您的更改方面有一个长途

  • 从功能更改中分离错误修复。根据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 upstream feature_antigravity 反向推送:git push upstream :feature_antigravity