| 1 |
=========================== |
| 2 |
Working with Git and GitHub |
| 3 |
=========================== |
| 4 |
|
| 5 |
This section explains how the community can contribute code to Django via pull |
| 6 |
requests. If you're interested in how :ref:`mergers <mergers-team>` handle |
| 7 |
them, see :doc:`../committing-code`. |
| 8 |
|
| 9 |
Below, we are going to show how to create a GitHub pull request containing the |
| 10 |
changes for Trac ticket #xxxxx. By creating a fully-ready pull request, you |
| 11 |
will make the reviewer's job easier, meaning that your work is more likely to |
| 12 |
be merged into Django. |
| 13 |
|
| 14 |
You could also upload a traditional patch to Trac, but it's less practical for |
| 15 |
reviews. |
| 16 |
|
| 17 |
Installing Git |
| 18 |
============== |
| 19 |
|
| 20 |
Django uses `Git`_ for its source control. You can `download |
| 21 |
<https://git-scm.com/download>`_ Git, but it's often easier to install with |
| 22 |
your operating system's package manager. |
| 23 |
|
| 24 |
Django's `Git repository`_ is hosted on `GitHub`_, and it is recommended |
| 25 |
that you also work using GitHub. |
| 26 |
|
| 27 |
After installing Git, the first thing you should do is set up your name and |
| 28 |
email: |
| 29 |
|
| 30 |
.. code-block:: shell |
| 31 |
|
| 32 |
$ git config --global user.name "Your Real Name" |
| 33 |
$ git config --global user.email "[email protected]" |
| 34 |
|
| 35 |
Note that ``user.name`` should be your real name, not your GitHub nick. GitHub |
| 36 |
should know the email you use in the ``user.email`` field, as this will be |
| 37 |
used to associate your commits with your GitHub account. |
| 38 |
|
| 39 |
.. _Git: https://git-scm.com/ |
| 40 |
.. _Git repository: https://github.com/django/django/ |
| 41 |
.. _GitHub: https://github.com/ |
| 42 |
|
| 43 |
Setting up local repository |
| 44 |
=========================== |
| 45 |
|
| 46 |
When you have created your GitHub account, with the nick "GitHub_nick", and |
| 47 |
`forked Django's repository <https://github.com/django/django/fork>`__, |
| 48 |
create a local copy of your fork: |
| 49 |
|
| 50 |
.. code-block:: shell |
| 51 |
|
| 52 |
git clone https://github.com/GitHub_nick/django.git |
| 53 |
|
| 54 |
This will create a new directory "django", containing a clone of your GitHub |
| 55 |
repository. The rest of the git commands on this page need to be run within the |
| 56 |
cloned directory, so switch to it now: |
| 57 |
|
| 58 |
.. code-block:: shell |
| 59 |
|
| 60 |
cd django |
| 61 |
|
| 62 |
Your GitHub repository will be called "origin" in Git. |
| 63 |
|
| 64 |
You should also set up ``django/django`` as an "upstream" remote (that is, tell |
| 65 |
git that the reference Django repository was the source of your fork of it): |
| 66 |
|
| 67 |
.. code-block:: shell |
| 68 |
|
| 69 |
git remote add upstream https://github.com/django/django.git |
| 70 |
git fetch upstream |
| 71 |
|
| 72 |
You can add other remotes similarly, for example: |
| 73 |
|
| 74 |
.. code-block:: shell |
| 75 |
|
| 76 |
git remote add akaariai https://github.com/akaariai/django.git |
| 77 |
|
| 78 |
Working on a ticket |
| 79 |
=================== |
| 80 |
|
| 81 |
When working on a ticket, create a new branch for the work, and base that work |
| 82 |
on ``upstream/main``: |
| 83 |
|
| 84 |
.. code-block:: shell |
| 85 |
|
| 86 |
git checkout -b ticket_xxxxx upstream/main |
| 87 |
|
| 88 |
The -b flag creates a new branch for you locally. Don't hesitate to create new |
| 89 |
branches even for the smallest things - that's what they are there for. |
| 90 |
|
| 91 |
If instead you were working for a fix on the 1.4 branch, you would do: |
| 92 |
|
| 93 |
.. code-block:: shell |
| 94 |
|
| 95 |
git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x |
| 96 |
|
| 97 |
Assume the work is carried on the ticket_xxxxx branch. Make some changes and |
| 98 |
commit them: |
| 99 |
|
| 100 |
.. code-block:: shell |
| 101 |
|
| 102 |
git commit |
| 103 |
|
| 104 |
When writing the commit message, follow the :ref:`commit message |
| 105 |
guidelines <committing-guidelines>` to ease the work of the merger. If you're |
| 106 |
uncomfortable with English, try at least to describe precisely what the commit |
| 107 |
does. |
| 108 |
|
| 109 |
If you need to do additional work on your branch, commit as often as |
| 110 |
necessary: |
| 111 |
|
| 112 |
.. code-block:: shell |
| 113 |
|
| 114 |
git commit -m 'Added two more tests for edge cases' |
| 115 |
|
| 116 |
Publishing work |
| 117 |
--------------- |
| 118 |
|
| 119 |
You can publish your work on GitHub by running: |
| 120 |
|
| 121 |
.. code-block:: shell |
| 122 |
|
| 123 |
git push origin ticket_xxxxx |
| 124 |
|
| 125 |
When you go to your GitHub page, you will notice a new branch has been created. |
| 126 |
|
| 127 |
If you are working on a Trac ticket, you should mention in the ticket that |
| 128 |
your work is available from branch ticket_xxxxx of your GitHub repo. Include a |
| 129 |
link to your branch. |
| 130 |
|
| 131 |
Note that the above branch is called a "topic branch" in Git parlance. You are |
| 132 |
free to rewrite the history of this branch, by using ``git rebase`` for |
| 133 |
example. Other people shouldn't base their work on such a branch, because |
| 134 |
their clone would become corrupt when you edit commits. |
| 135 |
|
| 136 |
There are also "public branches". These are branches other people are supposed |
| 137 |
to fork, so the history of these branches should never change. Good examples |
| 138 |
of public branches are the ``main`` and ``stable/A.B.x`` branches in the |
| 139 |
``django/django`` repository. |
| 140 |
|
| 141 |
When you think your work is ready to be pulled into Django, you should create |
| 142 |
a pull request at GitHub. A good pull request means: |
| 143 |
|
| 144 |
* commits with one logical change in each, following the |
| 145 |
:doc:`coding style <coding-style>`, |
| 146 |
|
| 147 |
* well-formed messages for each commit: a summary line and then paragraphs |
| 148 |
wrapped at 72 characters thereafter -- see the :ref:`committing guidelines |
| 149 |
<committing-guidelines>` for more details, |
| 150 |
|
| 151 |
* documentation and tests, if needed -- actually tests are always needed, |
| 152 |
except for documentation changes. |
| 153 |
|
| 154 |
The test suite must pass and the documentation must build without warnings. |
| 155 |
|
| 156 |
Once you have created your pull request, you should add a comment in the |
| 157 |
related Trac ticket explaining what you've done. In particular, you should note |
| 158 |
the environment in which you ran the tests, for instance: "all tests pass |
| 159 |
under SQLite and MySQL". |
| 160 |
|
| 161 |
Pull requests at GitHub have only two states: open and closed. The merger who |
| 162 |
will deal with your pull request has only two options: merge it or close it. |
| 163 |
For this reason, it isn't useful to make a pull request until the code is ready |
| 164 |
for merging -- or sufficiently close that a merger will finish it themselves. |
| 165 |
|
| 166 |
Rebasing branches |
| 167 |
----------------- |
| 168 |
|
| 169 |
In the example above, you created two commits, the "Fixed ticket_xxxxx" commit |
| 170 |
and "Added two more tests" commit. |
| 171 |
|
| 172 |
We do not want to have the entire history of your working process in your |
| 173 |
repository. Your commit "Added two more tests" would be unhelpful noise. |
| 174 |
Instead, we would rather only have one commit containing all your work. |
| 175 |
|
| 176 |
To rework the history of your branch you can squash the commits into one by |
| 177 |
using interactive rebase: |
| 178 |
|
| 179 |
.. code-block:: shell |
| 180 |
|
| 181 |
git rebase -i HEAD~2 |
| 182 |
|
| 183 |
The HEAD~2 above is shorthand for two latest commits. The above command |
| 184 |
will open an editor showing the two commits, prefixed with the word "pick". |
| 185 |
|
| 186 |
Change "pick" on the second line to "squash" instead. This will keep the |
| 187 |
first commit, and squash the second commit into the first one. Save and quit |
| 188 |
the editor. A second editor window should open, so you can reword the |
| 189 |
commit message for the commit now that it includes both your steps. |
| 190 |
|
| 191 |
You can also use the "edit" option in rebase. This way you can change a single |
| 192 |
commit, for example to fix a typo in a docstring: |
| 193 |
|
| 194 |
.. code-block:: shell |
| 195 |
|
| 196 |
git rebase -i HEAD~3 |
| 197 |
# Choose edit, pick, pick for the commits |
| 198 |
# Now you are able to rework the commit (use git add normally to add changes) |
| 199 |
# When finished, commit work with "--amend" and continue |
| 200 |
git commit --amend |
| 201 |
# Reword the commit message if needed |
| 202 |
git rebase --continue |
| 203 |
# The second and third commits should be applied. |
| 204 |
|
| 205 |
If your topic branch is already published at GitHub, for example if you're |
| 206 |
making minor changes to take into account a review, you will need to force-push |
| 207 |
the changes: |
| 208 |
|
| 209 |
.. code-block:: shell |
| 210 |
|
| 211 |
git push -f origin ticket_xxxxx |
| 212 |
|
| 213 |
Note that this will rewrite history of ticket_xxxxx - if you check the commit |
| 214 |
hashes before and after the operation at GitHub you will notice that the commit |
| 215 |
hashes do not match anymore. This is acceptable, as the branch is a topic |
| 216 |
branch, and nobody should be basing their work on it. |
| 217 |
|
| 218 |
After upstream has changed |
| 219 |
-------------------------- |
| 220 |
|
| 221 |
When upstream (``django/django``) has changed, you should rebase your work. To |
| 222 |
do this, use: |
| 223 |
|
| 224 |
.. code-block:: shell |
| 225 |
|
| 226 |
git fetch upstream |
| 227 |
git rebase upstream/main |
| 228 |
|
| 229 |
The work is automatically rebased using the branch you forked on, in the |
| 230 |
example case using ``upstream/main``. |
| 231 |
|
| 232 |
The rebase command removes all your local commits temporarily, applies the |
| 233 |
upstream commits, and then applies your local commits again on the work. |
| 234 |
|
| 235 |
If there are merge conflicts, you will need to resolve them and then use ``git |
| 236 |
rebase --continue``. At any point you can use ``git rebase --abort`` to return |
| 237 |
to the original state. |
| 238 |
|
| 239 |
Note that you want to *rebase* on upstream, not *merge* the upstream. |
| 240 |
|
| 241 |
The reason for this is that by rebasing, your commits will always be *on |
| 242 |
top of* the upstream's work, not *mixed in with* the changes in the upstream. |
| 243 |
This way your branch will contain only commits related to its topic, which |
| 244 |
makes squashing easier. |
| 245 |
|
| 246 |
After review |
| 247 |
------------ |
| 248 |
|
| 249 |
It is unusual to get any non-trivial amount of code into core without changes |
| 250 |
requested by reviewers. In this case, it is often a good idea to add the |
| 251 |
changes as one incremental commit to your work. This allows the reviewer to |
| 252 |
easily check what changes you have done. |
| 253 |
|
| 254 |
In this case, do the changes required by the reviewer. Commit as often as |
| 255 |
necessary. Before publishing the changes, rebase your work. If you added two |
| 256 |
commits, you would run: |
| 257 |
|
| 258 |
.. code-block:: shell |
| 259 |
|
| 260 |
git rebase -i HEAD~2 |
| 261 |
|
| 262 |
Squash the second commit into the first. Write a commit message along the lines |
| 263 |
of: |
| 264 |
|
| 265 |
.. code-block:: text |
| 266 |
|
| 267 |
Made changes asked in review by <reviewer> |
| 268 |
|
| 269 |
- Fixed whitespace errors in foobar |
| 270 |
- Reworded the docstring of bar() |
| 271 |
|
| 272 |
Finally, push your work back to your GitHub repository. Since you didn't touch |
| 273 |
the public commits during the rebase, you should not need to force-push: |
| 274 |
|
| 275 |
.. code-block:: shell |
| 276 |
|
| 277 |
git push origin ticket_xxxxx |
| 278 |
|
| 279 |
Your pull request should now contain the new commit too. |
| 280 |
|
| 281 |
Note that the merger is likely to squash the review commit into the previous |
| 282 |
commit when committing the code. |
| 283 |
|
| 284 |
Working on a patch |
| 285 |
================== |
| 286 |
|
| 287 |
One of the ways that developers can contribute to Django is by reviewing |
| 288 |
patches. Those patches will typically exist as pull requests on GitHub and |
| 289 |
can be easily integrated into your local repository: |
| 290 |
|
| 291 |
.. code-block:: shell |
| 292 |
|
| 293 |
git checkout -b pull_xxxxx upstream/main |
| 294 |
curl -L https://github.com/django/django/pull/xxxxx.patch | git am |
| 295 |
|
| 296 |
This will create a new branch and then apply the changes from the pull request |
| 297 |
to it. At this point you can run the tests or do anything else you need to |
| 298 |
do to investigate the quality of the patch. |
| 299 |
|
| 300 |
For more detail on working with pull requests see the |
| 301 |
:ref:`guidelines for mergers <handling-pull-requests>`. |
| 302 |
|
| 303 |
Summary |
| 304 |
======= |
| 305 |
|
| 306 |
* Work on GitHub if you can. |
| 307 |
* Announce your work on the Trac ticket by linking to your GitHub branch. |
| 308 |
* When you have something ready, make a pull request. |
| 309 |
* Make your pull requests as good as you can. |
| 310 |
* When doing fixes to your work, use ``git rebase -i`` to squash the commits. |
| 311 |
* When upstream has changed, do ``git fetch upstream; git rebase``. |