Debian Codegraph @

docs/internals/contributing/committing-code.txt

raw
1 ===============
2 Committing code
3 ===============
4
5 This section is addressed to the mergers and to anyone interested in knowing
6 how code gets committed into Django. If you're a community member who wants to
7 contribute code to Django, look at :doc:`writing-code/working-with-git` instead.
8
9 .. _handling-pull-requests:
10
11 Handling pull requests
12 ======================
13
14 Since Django is hosted on GitHub, patches are provided in the form of pull
15 requests.
16
17 When committing a pull request, make sure each individual commit matches the
18 commit guidelines described below. Contributors are expected to provide the
19 best pull requests possible. In practice mergers - who will likely be more
20 familiar with the commit guidelines - may decide to bring a commit up to
21 standard themselves.
22
23 You may want to have Jenkins or GitHub actions test the pull request with one
24 of the pull request builders that doesn't run automatically, such as Oracle or
25 Selenium. See the `CI wiki page`_ for instructions.
26
27 .. _CI wiki page: https://code.djangoproject.com/wiki/CI
28
29 If you find yourself checking out pull requests locally more often, this git
30 alias will be helpful:
31
32 .. code-block:: ini
33
34 [alias]
35 pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\"
36
37 Add it to your ``~/.gitconfig``, and set ``upstream`` to be ``django/django``.
38 Then you can run ``git pr ####`` to checkout the corresponding pull request.
39
40 At this point, you can work on the code. Use ``git rebase -i`` and ``git
41 commit --amend`` to make sure the commits have the expected level of quality.
42 Once you're ready:
43
44 .. console::
45
46 $ # Pull in the latest changes from main.
47 $ git checkout main
48 $ git pull upstream main
49 $ # Rebase the pull request on main.
50 $ git checkout pr/####
51 $ git rebase main
52 $ git checkout main
53 $ # Merge the work as "fast-forward" to main to avoid a merge commit.
54 $ # (in practice, you can omit "--ff-only" since you just rebased)
55 $ git merge --ff-only pr/XXXX
56 $ # If you're not sure if you did things correctly, check that only the
57 $ # changes you expect will be pushed to upstream.
58 $ git push --dry-run upstream main
59 $ # Push!
60 $ git push upstream main
61 $ # Delete the pull request branch.
62 $ git branch -d pr/xxxx
63
64 Force push to the branch after rebasing on main but before merging and pushing
65 to upstream. This allows the commit hashes on main and the branch to match
66 which automatically closes the pull request.
67
68 If a pull request doesn't need to be merged as multiple commits, you can use
69 GitHub's "Squash and merge" button on the website. Edit the commit message as
70 needed to conform to :ref:`the guidelines <committing-guidelines>` and remove
71 the pull request number that's automatically appended to the message's first
72 line.
73
74 When rewriting the commit history of a pull request, the goal is to make
75 Django's commit history as usable as possible:
76
77 * If a patch contains back-and-forth commits, then rewrite those into one.
78 For example, if a commit adds some code and a second commit fixes stylistic
79 issues introduced in the first commit, those commits should be squashed
80 before merging.
81
82 * Separate changes to different commits by logical grouping: if you do a
83 stylistic cleanup at the same time as you do other changes to a file,
84 separating the changes into two different commits will make reviewing
85 history easier.
86
87 * Beware of merges of upstream branches in the pull requests.
88
89 * Tests should pass and docs should build after each commit. Neither the
90 tests nor the docs should emit warnings.
91
92 * Trivial and small patches usually are best done in one commit. Medium to
93 large work may be split into multiple commits if it makes sense.
94
95 Practicality beats purity, so it is up to each merger to decide how much
96 history mangling to do for a pull request. The main points are engaging the
97 community, getting work done, and having a usable commit history.
98
99 .. _committing-guidelines:
100
101 Committing guidelines
102 =====================
103
104 In addition, please follow the following guidelines when committing code to
105 Django's Git repository:
106
107 * Never change the published history of ``django/django`` branches by force
108 pushing. If you absolutely must (for security reasons for example), first
109 discuss the situation with the team.
110
111 * For any medium-to-big changes, where "medium-to-big" is according to
112 your judgment, please bring things up on the `Django Forum`_ before making
113 the change.
114
115 If you bring something up and nobody responds, please don't take that
116 to mean your idea is great and should be implemented immediately because
117 nobody contested it. Everyone doesn't always have a lot of time to read
118 discussions immediately, so you may have to wait a couple of days before
119 getting a response.
120
121 * Write detailed commit messages in the past tense, not present tense.
122
123 * Good: "Fixed Unicode bug in RSS API."
124 * Bad: "Fixes Unicode bug in RSS API."
125 * Bad: "Fixing Unicode bug in RSS API."
126
127 The commit message should be in lines of 72 chars maximum. There should be
128 a subject line, separated by a blank line and then paragraphs of 72 char
129 lines. The limits are soft. For the subject line, shorter is better. In the
130 body of the commit message more detail is better than less:
131
132 .. code-block:: none
133
134 Fixed #18307 -- Added git workflow guidelines.
135
136 Refactored the Django's documentation to remove mentions of SVN
137 specific tasks. Added guidelines of how to use Git, GitHub, and
138 how to use pull request together with Trac instead.
139
140 Credit the contributors in the commit message: "Thanks A for the report and B
141 for review." Use git's `Co-Authored-By`_ as appropriate.
142
143 .. _Co-Authored-By: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors
144
145 * For commits to a branch, prefix the commit message with the branch name.
146 For example: "[1.4.x] Fixed #xxxxx -- Added support for mind reading."
147
148 * Limit commits to the most granular change that makes sense. This means,
149 use frequent small commits rather than infrequent large commits. For
150 example, if implementing feature X requires a small change to library Y,
151 first commit the change to library Y, then commit feature X in a separate
152 commit. This goes a *long way* in helping everyone follow your changes.
153
154 * Separate bug fixes from feature changes. Bugfixes may need to be backported
155 to the stable branch, according to :ref:`supported-versions-policy`.
156
157 * If your commit closes a ticket in the Django `ticket tracker`_, begin
158 your commit message with the text "Fixed #xxxxx", where "xxxxx" is the
159 number of the ticket your commit fixes. Example: "Fixed #123 -- Added
160 whizbang feature.". We've rigged Trac so that any commit message in that
161 format will automatically close the referenced ticket and post a comment
162 to it with the full commit message.
163
164 For the curious, we're using a `Trac plugin`_ for this.
165
166 .. note::
167
168 Note that the Trac integration doesn't know anything about pull requests.
169 So if you try to close a pull request with the phrase "closes #400" in your
170 commit message, GitHub will close the pull request, but the Trac plugin
171 will not close the same numbered ticket in Trac.
172
173 .. _Trac plugin: https://github.com/trac-hacks/trac-github
174
175 * If your commit references a ticket in the Django `ticket tracker`_ but
176 does *not* close the ticket, include the phrase "Refs #xxxxx", where "xxxxx"
177 is the number of the ticket your commit references. This will automatically
178 post a comment to the appropriate ticket.
179
180 * Write commit messages for backports using this pattern:
181
182 .. code-block:: none
183
184 [<Django version>] Fixed <ticket> -- <description>
185
186 Backport of <revision> from <branch>.
187
188 For example:
189
190 .. code-block:: none
191
192 [1.3.x] Fixed #17028 -- Changed diveintopython.org -> diveintopython.net.
193
194 Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.
195
196 There's a `script on the wiki
197 <https://code.djangoproject.com/wiki/MergerTips#AutomatingBackports>`_ to
198 automate this.
199
200 If the commit fixes a regression, include this in the commit message:
201
202 .. code-block:: none
203
204 Regression in 6ecccad711b52f9273b1acb07a57d3f806e93928.
205
206 (use the commit hash where the regression was introduced).
207
208 Reverting commits
209 =================
210
211 Nobody's perfect; mistakes will be committed.
212
213 But try very hard to ensure that mistakes don't happen. Just because we have a
214 reversion policy doesn't relax your responsibility to aim for the highest
215 quality possible. Really: double-check your work, or have it checked by
216 another merger **before** you commit it in the first place!
217
218 When a mistaken commit is discovered, please follow these guidelines:
219
220 * If possible, have the original author revert their own commit.
221
222 * Don't revert another author's changes without permission from the
223 original author.
224
225 * Use git revert -- this will make a reverse commit, but the original
226 commit will still be part of the commit history.
227
228 * If the original author can't be reached (within a reasonable amount
229 of time -- a day or so) and the problem is severe -- crashing bug,
230 major test failures, etc. -- then ask for objections on the `Django Forum`_
231 then revert if there are none.
232
233 * If the problem is small (a feature commit after feature freeze,
234 say), wait it out.
235
236 * If there's a disagreement between the merger and the reverter-to-be then try
237 to work it out on the `Django Forum`_ . If an agreement can't be reached then
238 it should be put to a vote.
239
240 * If the commit introduced a confirmed, disclosed security
241 vulnerability then the commit may be reverted immediately without
242 permission from anyone.
243
244 * The release branch maintainer may back out commits to the release
245 branch without permission if the commit breaks the release branch.
246
247 * If you mistakenly push a topic branch to ``django/django``, delete it.
248 For instance, if you did: ``git push upstream feature_antigravity``,
249 do a reverse push: ``git push upstream :feature_antigravity``.
250
251 .. _ticket tracker: https://code.djangoproject.com/
252 .. _Django Forum: https://forum.djangoproject.com/