This section is addressed to the mergers and to anyone interested in knowing how code gets committed into Django. The 提交指南 apply to all contributors, with or without commit rights.
如果您是想向 Django 贡献代码的社区成员，请前往查看 使用 Git 和 GitHub 工作。
因为Django现在是托管在GitHub上的，所以大多数补丁都是以 pull requests 的形式提供的。
提交拉取请求时，请确保每个单独的提交符合下面描述的提交准则。我们期望贡献者提供最好的拉取请求。在实践中，合并者（很可能更熟悉提交准则）可能会决定自行将提交符合标准。
你可能希望使用 Jenkins 或 GitHub actions 来测试拉取请求，其中之一是不会自动运行的拉取请求构建器，比如 Oracle 或 Selenium。请查看 CI wiki 页面 获取说明。
如果您发现自己经常在本地检出拉取请求，这个 Git 别名将会很有帮助：
[alias]
pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"
将它添加到你的 ~/.gitconfig 文件中，并且把 upstream 改为 django/django 。然后你就可以通过运行 git pr #### 来检出对应的 pull request 了。
到了这个阶段,你可以着手于代码.使用"git rebase -i"和"git commit --ammend" 来确保你的提交准确无误. 一旦你准备好了:
$ # Pull in the latest changes from main.
$ git checkout main
$ git pull upstream main
$ # Rebase the pull request on main.
$ git checkout pr/####
$ git rebase main
$ git checkout main
$ # Merge the work as "fast-forward" to main 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 main
$ # Push!
$ git push upstream main
$ # Delete the pull request branch.
$ git branch -d pr/xxxx
...\> REM Pull in the latest changes from main.
...\> git checkout main
...\> git pull upstream main
...\> REM Rebase the pull request on main.
...\> git checkout pr/####
...\> git rebase main
...\> git checkout main
...\> REM Merge the work as "fast-forward" to main to avoid a merge commit.
...\> REM (in practice, you can omit "--ff-only" since you just rebased)
...\> git merge --ff-only pr/XXXX
...\> REM If you're not sure if you did things correctly, check that only the
...\> REM changes you expect will be pushed to upstream.
...\> git push --dry-run upstream main
...\> REM Push!
...\> git push upstream main
...\> REM Delete the pull request branch.
...\> git branch -d pr/xxxx
在将主分支重新基于重置后、合并并推送到上游之前，强制推送到分支。这样可以使主分支和分支上的提交哈希匹配，自动关闭拉取请求。
如果拉请求不需要合并为多个提交，则可以在网页上使用 Github 的“Squash and merge”按钮。根据需要编辑提交消息以符合 指南 并删除自动附加到消息第一行的请求编号。
当重写pull请求的提交历史时，目标是使Django的提交历史尽可能可用：
如果补丁包含来回提交，则将其重写为一个。例如，如果提交添加了一些代码，第二个提交修复了第一次提交中引入的样式问题，那么这些提交应该在合并之前被压缩。
通过逻辑分组对不同提交进行单独更改：如果在对文件进行其他更改的同时进行样式清理，则将更改分成两个不同的提交将使查看历史记录变得更容易。
注意拉取请求中上游分支的合并。
测试应该通过，文档应该在每次提交后构建。测试和文档都不应该发出警告。
随意和小型的补丁通常最好在一次提交中完成。如果有意义，可以将中型到大型工作分成多个提交。
实用性胜过纯粹性，因此由每个合并者决定拉取请求的历史重塑程度。主要目标是与社区互动、完成工作并拥有可用的提交历史。
These guidelines apply to all commits to Django's Git repository, whether submitted by a contributor via a pull request or landed directly by a merger:
永远不要通过强制推动来改变“django / django``分支的已发布历史。如果您绝对必须（出于安全原因），请先与团队讨论情况。
For any medium-to-big changes, where "medium-to-big" is according to your judgment, please bring things up on the Django Forum before making the change.
If you bring something up and nobody responds, please don't take that to mean your idea is great and should be implemented immediately because nobody contested it. Everyone doesn't always have a lot of time to read discussions immediately, so you may have to wait a couple of days before getting a response.
Write detailed commit messages in the past tense, not present tense, and end the subject line with a period.
正确："Fixed Unicode bug in RSS API."
错误："Fixes Unicode bug in RSS API."（用了现在时）
错误："Fixing Unicode bug in RSS API."（用了"-ing"形式）
错误："Fixed Unicode bug in RSS API"（缺句号）
提交消息最多应为72个字符。 应该有一个主题行，用空白行分隔，然后是72个字符行的段落。 限制很松。 对于主题行，越短越好。 在提交消息的主体中，更多细节优于更少。
In the body of the commit message more detail is better than less, and should explain why the change was made, not what was changed or how. The code itself shows what changed; the commit message should provide the context and reasoning that the code cannot.
Credit the contributors in the commit message: "Thanks A for the report and B for review." Use git's Co-Authored-By as appropriate, including anyone whose earlier work the change builds on.
例如：
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.
Thanks to Full Name for the report, and to Reviewer for reviews.
限制承诺最细微的变化是有意义的。这意味着，使用频繁的小额承诺，而不是很少的大额承诺。例如，如果实现功能X需要对库Y做一个小的更改，那么首先将更改提交到库Y，然后在单独的提交中提交功能X。这对帮助每个人跟踪你的变化有很大的帮助。
Separate bug fixes from feature changes. Bugfixes may need to be backported.
如果你的提交解决了 Django ticket tracker 中的一个 ticket，请在提交信息的开头添加 "Fixed #xxxxx"，其中 ”xxxxx" 是你提交所解决的 ticket 的编号。示例："Fixed #123 -- Added whizbang feature." 。当系统检测到这种提交信息格式时，系统会自动关闭所指向的 ticket 并将完整的提交信息作为评论发出。
如果你好奇的话，我们使用 Trac plugin 来实现这种机制。
Note
请注意，Trac 集成对拉取请求一无所知。因此，如果你在提交信息中使用了 " closes #400 " 这样的短语来关闭拉取请求，GitHub 将关闭该拉取请求，但 Trac 插件将不会关闭 Trac 中相同编号的工单。
如果你只想要在提交信息中引用 Django ticket tracker 中的某个 ticket ，但并*不*想要关闭它时，可以使用 “Ref #xxxxx"，其中 "xxxxx" 是你的提交想引用的 ticket 的编号。这会触发系统自动的在被引用的 ticket 下发送一条评论。
Bug fix backports to stable branches are done exclusively by mergers, following
the 支持的版本. A backport consists of cherry-picking a
commit from main onto the target stable/A.B.x branch.
A backport commit must include two things beyond the original commit message:
A prefix [A.B.x] on the subject line, where A.B.x is the name of the
stable/A.B.x branch being targeted.
A suffix Backport of <sha> from main. line in the commit body, pointing
to the original commit hash.
例如：
[1.3.x] Fixed #17028 -- Changed diveintopython.org -> diveintopython.net.
Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.
If the backport also fixes a regression, add a line identifying the commit that introduced it:
Regression in 6ecccad711b52f9273b1acb07a57d3f806e93928.
There are three ways to do a backport, depending on your workflow:
Option 1: fully manual
Cherry-pick the commit onto the stable branch, then amend the commit message to add the required prefix and backport note:
git cherry-pick <sha>
git commit --amend
If the cherry-pick produces conflicts, resolve them, stage the changes, then
run git cherry-pick --continue before amending. This option requires no
setup but relies entirely on remembering to format the message correctly.
Option 2: using the helper script in the repo
The scripts/backport.sh Bash script automates the cherry-pick and rewrites
the commit message with the correct prefix and backport note. Run it from the
target stable branch:
bash scripts/backport.sh <sha>
This is straightforward for clean cherry-picks, but if conflicts are produced, you will need to resolve them manually and add the prefix and backport note to the commit message yourself.
Option 3: using the prepare-commit-msg git hook
The scripts/prepare_commit_msg.py Python script can be installed as a
prepare-commit-msg git hook. It automatically adds the [A.B.x] prefix
to the subject line, appends Backport of <sha> from main. to the commit
body, and ensures the subject line ends with a period, even when the
cherry-pick produces conflicts. To install it, create an executable file
.git/hooks/prepare-commit-msg containing:
#!/bin/sh
exec python scripts/prepare_commit_msg.py "$@"
Once installed, a plain git cherry-pick <sha> on a stable branch is
sufficient; the hook handles the message formatting in all cases.
没有人是完美的；一些错误可能会被提交
但要尽力确保不出现错误。仅仅因为我们有一个回退政策并不意味着你的责任就可以放松，你仍然需要追求最高的质量。真的：在首次提交之前，仔细检查你的工作，或者让另一个合并者在你提交之前检查它！
当你发现了一个错误的提交，请遵循如下步骤：
可能的话，让原始作者撤回他们的提交。
不要在未获得原始作者同意的情况下还原其他作者的更改。
使用 git revert -- 会回退提交，但原提交依然会留在提交历史中。
If the original author can't be reached (within a reasonable amount of time -- a day or so) and the problem is severe -- crashing bug, major test failures, etc. -- then ask for objections on the Django Forum then revert if there are none.
如果问题不大（比如说冻结后的提交），就等着吧。
If there's a disagreement between the merger and the reverter-to-be then try to work it out on the Django Forum . If an agreement can't be reached then it should be put to a vote.
如果该提交引入了一个已确认或已披露的安全漏洞，那么该提交可能会在未经任何允许的情况下被立即还原。
如果提交的内容破坏了发布分支，发布分支的维护者可以在不经许可的情况下将该提交回退。
如果错误地将主题分支推送到 "django/django"，请将其删除。例如，如果你做了：git push upstream feature_antigravity`，那么做一个反向推送：git push upstream:feature_antigravity。
8月 05, 2026