使用 Git 和 GitHub 工作

This section explains how the community can contribute code to Django via pull requests. If you’re interested in how mergers handle them, see 提交代码.

Below, we are going to show how to create a GitHub pull request containing the changes for Trac ticket #xxxxx. By creating a fully-ready pull request, you will make the reviewer’s job easier, meaning that your work is more likely to be merged into Django.

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

安装 Git

Django uses Git for its source control. You can download Git, but it’s often easier to install with your operating system’s package manager.

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

After installing Git, the first thing you should do is set up your name and email:

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

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

设置本地仓库

When you have created your GitHub account, with the nick “GitHub_nick”, and forked Django’s repository, create a local copy of your fork:

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

This will create a new directory “django”, containing a clone of your GitHub repository. The rest of the git commands on this page need to be run within the cloned directory, so switch to it now:

  1. cd django

在 Git 中，你的 Github 仓库会被称做“origin”。

You should also set up django/django as an “upstream” remote (that is, tell git that the reference Django repository was the source of your fork of it):

  1. git remote add upstream https://github.com/django/django.git
  2. git fetch upstream

You can add other remotes similarly, for example:

  1. git remote add akaariai https://github.com/akaariai/django.git

在工单上工作

When working on a ticket, create a new branch for the work, and base that work on upstream/main:

  1. git checkout -b ticket_xxxxx upstream/main

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

If instead you were working for a fix on the 1.4 branch, you would do:

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

Assume the work is carried on the ticket_xxxxx branch. Make some changes and commit them:

  1. git commit

When writing the commit message, follow the commit message guidelines to ease the work of the merger. If you’re uncomfortable with English, try at least to describe precisely what the commit does.

If you need to do additional work on your branch, commit as often as necessary:

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

发布工作成果

You can publish your work on GitHub by running:

  1. git push origin ticket_xxxxx

When you go to your GitHub page, you will notice a new branch has been created.

If you are working on a Trac ticket, you should mention in the ticket that your work is available from branch ticket_xxxxx of your GitHub repo. Include a link to your branch.

请注意，在Git中，上述分支称为“主题分支”。 您可以自由地重写该分支的历史记录，例如，使用 git rebase 变更基本。 其他人不应在这样的分支上进行工作，因为当您编辑提交时，他们的副本会损坏。

There are also “public branches”. These are branches other people are supposed to fork, so the history of these branches should never change. Good examples of public branches are the main and stable/A.B.x branches in the django/django repository.

当您准备将工作成果并入Django时，应在GitHub上创建一个pull请求。好的拉取请求要求：

  • 按照:doc:coding style <coding-style> ，每个提交都进行一次逻辑更改，
  • 每次提交的格式正确的消息：摘要行，其后以72个字符包装的段落——有关详细信息，请参见 committing guidelines 。
  • 如果需要，带有文档和测试——实际上一直需要测试，除了文档更改外。

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

Once you have created your pull request, you should add a comment in the related Trac ticket explaining what you’ve done. In particular, you should note the environment in which you ran the tests, for instance: “all tests pass under SQLite and MySQL”.

Pull requests at GitHub have only two states: open and closed. The merger who will deal with your pull request has only two options: merge it or close it. For this reason, it isn’t useful to make a pull request until the code is ready for merging — or sufficiently close that a merger will finish it themselves.

分支变基

In the example above, you created two commits, the “Fixed ticket_xxxxx” commit and “Added two more tests” commit.

我们不想在您的代码库中拥有您工作过程的全部历史记录。您的提交“添加了两个以上的测试”将毫无助益。相反，我们只希望一次提交包含您的所有工作。

To rework the history of your branch you can squash the commits into one by using interactive rebase:

  1. git rebase -i HEAD~2

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

Change “pick” on the second line to “squash” instead. This will keep the first commit, and squash the second commit into the first one. Save and quit the editor. A second editor window should open, so you can reword the commit message for the commit now that it includes both your steps.

You can also use the “edit” option in rebase. This way you can change a single commit, for example to fix a typo in a docstring:

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

If your topic branch is already published at GitHub, for example if you’re making minor changes to take into account a review, you will need to force-push the changes:

  1. git push -f origin ticket_xxxxx

Note that this will rewrite history of ticket_xxxxx - if you check the commit hashes before and after the operation at GitHub you will notice that the commit hashes do not match anymore. This is acceptable, as the branch is a topic branch, and nobody should be basing their work on it.

在上游发生变化之后

When upstream (django/django) has changed, you should rebase your work. To do this, use:

  1. git fetch upstream
  2. git rebase upstream/main

The work is automatically rebased using the branch you forked on, in the example case using upstream/main.

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

If there are merge conflicts, you will need to resolve them and then use git rebase --continue. At any point you can use git rebase --abort to return to the original state.

请注意，您想在上游 变基 ，而不是 合并 上游。

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

审阅之后

在审核者未要求更改的情况下，将任何不重要的代码放入内核是很不正常的。 在这种情况下，通常最好将更改添加为对工作的一次增量提交。 这使审阅者可以轻松地检查您所做的更改。

In this case, do the changes required by the reviewer. Commit as often as necessary. Before publishing the changes, rebase your work. If you added two commits, you would run:

  1. git rebase -i HEAD~2

Squash the second commit into the first. Write a commit message along the lines of:

  1. Made changes asked in review by <reviewer>
  3. - Fixed whitespace errors in foobar
  4. - Reworded the docstring of bar()

Finally, push your work back to your GitHub repository. Since you didn’t touch the public commits during the rebase, you should not need to force-push:

  1. git push origin ticket_xxxxx

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

Note that the merger is likely to squash the review commit into the previous commit when committing the code.

Working on a patch

One of the ways that developers can contribute to Django is by reviewing patches. Those patches will typically exist as pull requests on GitHub and can be easily integrated into your local repository:

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

This will create a new branch and then apply the changes from the pull request to it. At this point you can run the tests or do anything else you need to do to investigate the quality of the patch.

For more detail on working with pull requests see the guidelines for mergers.

概览

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