使用 Git 和 GitHub — Django 文档

使用 Git 和 GitHub

本节解释了社区如何通过拉取请求向 Django 贡献代码。 如果您对提交者如何处理它们感兴趣，请参阅 提交代码 。

下面，我们将展示如何创建包含 Trac 票 #xxxxx 更改的 GitHub 拉取请求。 通过创建一个完全准备好的拉取请求，您将使审阅者的工作更轻松，这意味着您的工作更有可能被合并到 Django 中。

您也可以将传统补丁上传到 Trac，但对于评论来说不太实用。

安装 Git

Django 使用 Git 进行源代码控制。 您可以 下载 Git，但使用操作系统的包管理器安装通常更容易。

Django的Git仓库托管在GitHub上，建议你也使用GitHub工作。

安装 Git 后，您应该做的第一件事是设置您的姓名和电子邮件：

$ git config --global user.name "Your Real Name"
$ git config --global user.email "you@email.com"

请注意，user.name 应该是您的真实姓名，而不是您的 GitHub 昵称。 GitHub 应该知道您在 user.email 字段中使用的电子邮件，因为这将用于将您的提交与您的 GitHub 帐户相关联。

设置本地存储库

创建 GitHub 帐户后，使用昵称“GitHub_nick”和 分叉 Django 的存储库 ，创建分叉的本地副本：

git clone https://github.com/GitHub_nick/django.git

这将创建一个新目录“django”，其中包含 GitHub 存储库的克隆。 此页面上的其余 git 命令需要在克隆目录中运行，因此现在切换到它：

cd django

您的 GitHub 存储库在 Git 中将被称为“origin”。

您还应该将 django/django 设置为“上游”远程（即，告诉 git 参考 Django 存储库是它的分支的来源）：

git remote add upstream git@github.com:django/django.git
git fetch upstream

您可以类似地添加其他遥控器，例如：

git remote add akaariai git@github.com:akaariai/django.git

处理票证

在处理工单时，为该工作创建一个新分支，并将该工作基于 upstream/main：

git checkout -b ticket_xxxxx upstream/main

-b 标志在本地为您创建一个新分支。 即使是最小的事情也不要犹豫，创建新的分支——这就是它们的目的。

相反，如果您正在修复 1.4 分支，您会这样做：

git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x

假设工作在 ticket_xxxxx 分支上进行。 进行一些更改并提交：

git commit

在编写提交消息时，请遵循 提交消息指南 以减轻提交者的工作。 如果您对英语感到不舒服，请至少尝试准确描述提交的作用。

如果你需要在你的分支上做额外的工作，根据需要经常提交：

git commit -m 'Added two more tests for edge cases'

出版工作

您可以通过运行以下命令在 GitHub 上发布您的工作：

git push origin ticket_xxxxx

当您转到 GitHub 页面时，您会注意到已经创建了一个新分支。

如果您正在处理 Trac 票证，则应在票证中提及您的工作可从 GitHub 存储库的分支 ticket_xxxxx 获得。 包括指向您的分支的链接。

请注意，上述分支在 Git 术语中称为“主题分支”。 您可以自由地重写此分支的历史记录，例如使用 git rebase。 其他人不应该将他们的工作建立在这样的分支上，因为当您编辑提交时，他们的克隆会损坏。

也有“公共分支”。 这些是其他人应该分叉的分支，所以这些分支的历史永远不应该改变。 公共分支的好例子是 django/django 存储库中的 main 和 stable/A.B.x 分支。

当您认为您的工作已准备好被拉入 Django 时，您应该在 GitHub 上创建一个拉取请求。 一个好的拉取请求意味着：

• 遵循 编码风格 ，在每个提交中进行一个逻辑更改，
• 每次提交的格式正确的消息：一个摘要行，然后是用 72 个字符包装的段落 - 有关更多详细信息，请参阅 提交指南 ，
• 文档和测试，如果需要——实际上测试总是需要的，除了文档更改。

测试套件必须通过并且文档必须在没有警告的情况下构建。

创建拉取请求后，您应该在相关的 Trac 票证中添加注释，解释您所做的工作。 特别是，您应该注意运行测试的环境，例如：“所有测试都在 SQLite 和 MySQL 下通过”。

GitHub 上的拉取请求只有两种状态：打开和关闭。 将处理您的拉取请求的提交者只有两个选择：合并或关闭它。 出于这个原因，在代码准备好合并之前发出拉取请求是没有用的 - 或者足够接近提交者将自己完成它。

变基分支

在上面的示例中，您创建了两个提交，“Fixed ticket_xxxxx”提交和“Added two more tests”提交。

我们不希望在您的存储库中拥有您工作过程的完整历史记录。 你的提交“增加了两个测试”将是无益的噪音。 相反，我们宁愿只有一个包含您所有工作的提交。

要修改分支的历史记录，您可以使用交互式 rebase 将提交压缩为一个：

git rebase -i HEAD~2

上面的 HEAD~2 是两个最新提交的简写。 上面的命令将打开一个编辑器，显示两个提交，前缀为“pick”。

将第二行的“pick”改为“squash”。 这将保留第一个提交，并将第二个提交压缩到第一个提交中。 保存并退出编辑器。 应该会打开第二个编辑器窗口，因此您可以改写提交的提交消息，因为它包括您的两个步骤。

您还可以使用 rebase 中的“编辑”选项。 通过这种方式，您可以更改单个提交，例如修复文档字符串中的拼写错误：

git rebase -i HEAD~3
# Choose edit, pick, pick for the commits
# Now you are able to rework the commit (use git add normally to add changes)
# When finished, commit work with "--amend" and continue
git commit --amend
# Reword the commit message if needed
git rebase --continue
# The second and third commits should be applied.

如果您的主题分支已经在 GitHub 上发布，例如，如果您正在进行细微的更改以考虑评论，您将需要强制推送更改：

git push -f origin ticket_xxxxx

请注意，这将重写 ticket_xxxxx 的历史记录 - 如果您在 GitHub 上检查操作前后的提交哈希，您会注意到提交哈希不再匹配。 这是可以接受的，因为该分支是一个主题分支，任何人都不应该以此为基础进行工作。

上游改变后

当上游 (django/django) 发生变化时，您应该重新调整您的工作。 为此，请使用：

git fetch upstream
git rebase

工作会使用您分叉的分支自动重新定位，在示例中使用 upstream/main。

rebase 命令会暂时删除所有本地提交，应用上游提交，然后再次将本地提交应用到工作中。

如果存在合并冲突，您需要解决它们，然后使用 git rebase --continue。 在任何时候都可以使用 git rebase --abort 返回到原始状态。

请注意，您希望在上游 rebase，而不是 merge 上游。

这样做的原因是通过变基，您的提交将始终 在 上游的工作之上，而不是 与 上游的更改混合在一起。 这样你的分支将只包含与其主题相关的提交，这使得压缩更容易。

审核后

在没有审阅者要求的更改的情况下将任何非平凡的代码量放入核心中是不寻常的。 在这种情况下，将更改添加为对工作的增量提交通常是一个好主意。 这使审阅者可以轻松检查您所做的更改。

在这种情况下，请执行审阅者要求的更改。 根据需要经常提交。 在发布更改之前，重新调整您的工作。 如果您添加了两次提交，您将运行：

git rebase -i HEAD~2

将第二个提交压缩到第一个中。 按照以下内容编写提交消息：

Made changes asked in review by <reviewer>

- Fixed whitespace errors in foobar
- Reworded the docstring of bar()

最后，将您的工作推送回您的 GitHub 存储库。 由于您在变基期间没有触及公共提交，因此您不需要强制推送：

git push origin ticket_xxxxx

您的拉取请求现在也应该包含新的提交。

请注意，提交者在提交代码时可能会将审查提交压缩到先前的提交中。

处理补丁

开发人员可以为 Django 做出贡献的一种方式是查看补丁。 这些补丁通常作为 GitHub 上的拉取请求存在，并且可以轻松集成到您的本地存储库中：

git checkout -b pull_xxxxx upstream/main
curl https://github.com/django/django/pull/xxxxx.patch | git am

这将创建一个新分支，然后将拉取请求中的更改应用到它。 此时，您可以运行测试或执行任何其他您需要做的事情来调查补丁的质量。

有关处理拉取请求的更多详细信息，请参阅提交者的 指南 。

总结

• 如果可以，请在 GitHub 上工作。
• 通过链接到您的 GitHub 分支来宣布您在 Trac 票证上的工作。
• 当你准备好东西时，提出一个拉取请求。
• 使您的拉取请求尽可能好。
• 在对您的工作进行修复时，请使用 git rebase -i 压缩提交。
• 当上游发生变化时，执行git fetch upstream; git rebase。