Debian Codegraph @

docs/internals/contributing/writing-code/working-with-git.txt

raw
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``.