本节针对Committers和任何有兴趣知道如何将代码提交到Django核心的任何人。如果你是一个社区成员想要贡献代码到Django,请看看Working with Git and GitHub。
由于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的提交历史尽可能地可用:
实用性击败纯度,所以由每个提交者决定多少历史记录为拉取请求做。主要的是参与社区,完成工作,并有一个可用的提交历史。
此外,当将代码提交到Django的Git存储库时,请遵循以下准则:
从不更改django / django分支的发布历史!不要强制将您的更改推送到django / django。如果你绝对必须(出于安全原因)首先与核心团队讨论情况。
对于任何中至大型更改,根据您的判断,“中到大”都要根据django-developers邮寄名单进行更改。
如果你在django-developers上提出问题,没有人回应,请不要这样说,这意味着你的想法是伟大的,应立即实施,因为没有人反对。Django的核心开发人员没有很多时间来立即阅读邮件列表讨论,因此您可能需要等待几天才能收到回复。
以过去时,不存在时编写详细提交消息。
提交消息的行数最多为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.
没有人是完美的;将犯下错误。
但要尽量确保错误不会发生。只是因为我们有一个回归政策不放松你的责任,以尽可能最高的质量为目标。真的:仔细检查你的工作,或者在另一个提交者之前检查你的工作,之前提交它!
发现错误提交时,请遵循以下准则:
2015年5月13日