← Back to branch summary

~ubuntu-branches/ubuntu/saucy/python-django/saucy-updates

« back to all changes in this revision

Viewing changes to docs/internals/contributing/committing-code.txt

  • Committer: Package Import Robot
  • Author(s): Luke Faraone, Jakub Wilk, Luke Faraone
  • Date: 2013-05-09 15:10:47 UTC
  • mfrom: (1.1.21) (4.4.27 sid)
  • Revision ID: package-import@ubuntu.com-20130509151047-aqv8d71oj9wvcv8c
Tags: 1.5.1-2
[ Jakub Wilk ]
* Use canonical URIs for Vcs-* fields.

[ Luke Faraone ]
* Upload to unstable.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/internals/contributing/committing-code.txt
3
3
===============
4
4
 
5
5
This section is addressed to the :doc:`/internals/committers` and to anyone
6
 
interested in knowing how code gets committed into Django core.
 
6
interested in knowing how code gets committed into Django core. If you're a
 
7
community member who wants to contribute code to Django, have a look at
 
8
:doc:`writing-code/working-with-git` instead.
7
9
 
8
10
Commit access
9
11
-------------
21
23
    access to the subsystems that fall under their jurisdiction, and they're
22
24
    given a formal vote in questions that involve their subsystems. This type
23
25
    of access is likely to be given to someone who contributes a large
24
 
    subframework to Django and wants to continue to maintain it.
 
26
    sub-framework to Django and wants to continue to maintain it.
25
27
 
26
28
    Partial commit access is granted by the same process as full
27
29
    committers. However, the bar is set lower; proven expertise in the area
30
32
Decisions on new committers will follow the process explained in
31
33
:ref:`how-we-make-decisions`. To request commit access, please contact an
32
34
existing committer privately. Public requests for commit access are potential
33
 
flame-war starters, and will be ignored.
 
35
flame-war starters, and will simply be ignored.
 
36
 
 
37
Handling pull requests
 
38
----------------------
 
39
 
 
40
Since Django is now hosted at GitHub, many patches are provided in the form of
 
41
pull requests.
 
42
 
 
43
When committing a pull request, make sure each individual commit matches the
 
44
commit guidelines described below. Contributors are expected to provide the
 
45
best pull requests possible. In practice however, committers - who will likely
 
46
be more familiar with the commit guidelines - may decide to bring a commit up
 
47
to standard themselves.
 
48
 
 
49
Here is one way to commit a pull request::
 
50
 
 
51
    # Create a new branch tracking upstream/master -- upstream is assumed
 
52
    # to be django/django.
 
53
    git checkout -b pull_xxxxx upstream/master
 
54
 
 
55
    # Download the patches from github and apply them.
 
56
    curl https://github.com/django/django/pull/xxxxx.patch | git am
 
57
 
 
58
At this point, you can work on the code. Use ``git rebase -i`` and ``git
 
59
commit --amend`` to make sure the commits have the expected level of quality.
 
60
Once you're ready::
 
61
 
 
62
    # Make sure master is ready to receive changes.
 
63
    git checkout master
 
64
    git pull upstream master
 
65
    # Merge the work as "fast-forward" to master, to avoid a merge commit.
 
66
    git merge --ff-only pull_xxxxx
 
67
    # Check that only the changes you expect will be pushed to upstream.
 
68
    git push --dry-run upstream master
 
69
    # Push!
 
70
    git push upstream master
 
71
 
 
72
    # Get rid of the pull_xxxxx branch.
 
73
    git branch -d pull_xxxxx
 
74
 
 
75
An alternative is to add the contributor's repository as a new remote,
 
76
checkout the branch and work from there::
 
77
 
 
78
    git remote add <contributor> https://github.com/<contributor>/django.git
 
79
    git checkout pull_xxxxx <contributor> <contributor's pull request branch>
 
80
 
 
81
Yet another alternative is to fetch the branch without adding the
 
82
contributor's repository as a remote::
 
83
 
 
84
    git fetch https://github.com/<contributor>/django.git <contributor's pull request branch>
 
85
    git checkout -b pull_xxxxx FETCH_HEAD
 
86
 
 
87
At this point, you can work on the code and continue as above.
 
88
 
 
89
GitHub provides a one-click merge functionality for pull requests. This should
 
90
only be used if the pull request is 100% ready, and you have checked it for
 
91
errors (or trust the request maker enough to skip checks). Currently, it isn't
 
92
possible to check that the tests pass and that the docs build without
 
93
downloading the changes to your development environment.
 
94
 
 
95
When rewriting the commit history of a pull request, the goal is to make
 
96
Django's commit history as usable as possible:
 
97
 
 
98
* If a patch contains back-and-forth commits, then rewrite those into one.
 
99
  Typically, a commit can add some code, and a second commit can fix
 
100
  stylistic issues introduced in the first commit.
 
101
 
 
102
* Separate changes to different commits by logical grouping: if you do a
 
103
  stylistic cleanup at the same time as you do other changes to a file,
 
104
  separating the changes into two different commits will make reviewing
 
105
  history easier.
 
106
 
 
107
* Beware of merges of upstream branches in the pull requests.
 
108
 
 
109
* Tests should pass and docs should build after each commit. Neither the
 
110
  tests nor the docs should emit warnings.
 
111
 
 
112
* Trivial and small patches usually are best done in one commit. Medium to
 
113
  large work should be split into multiple commits if possible.
 
114
 
 
115
Practicality beats purity, so it is up to each committer to decide how much
 
116
history mangling to do for a pull request. The main points are engaging the
 
117
community, getting work done, and having a usable commit history.
 
118
 
 
119
.. _committing-guidelines:
34
120
 
35
121
Committing guidelines
36
122
---------------------
37
123
 
38
 
Please follow these guidelines when committing code to Django's Subversion
39
 
repository:
 
124
In addition, please follow the following guidelines when committing code to
 
125
Django's Git repository:
 
126
 
 
127
* Never change the published history of django/django branches! **Never force-
 
128
  push your changes to django/django.** If you absolutely must (for security
 
129
  reasons for example) first discuss the situation with the core team.
40
130
 
41
131
* For any medium-to-big changes, where "medium-to-big" is according to
42
132
  your judgment, please bring things up on the `django-developers`_
55
145
  * Bad: "Fixes Unicode bug in RSS API."
56
146
  * Bad: "Fixing Unicode bug in RSS API."
57
147
 
 
148
  The commit message should be in lines of 72 chars maximum. There should be
 
149
  a subject line, separated by a blank line and then paragraphs of 72 char
 
150
  lines. The limits are soft. For the subject line, shorter is better. In the
 
151
  body of the commit message more detail is better than less::
 
152
 
 
153
      Fixed #18307 -- Added git workflow guidelines
 
154
 
 
155
      Refactored the Django's documentation to remove mentions of SVN
 
156
      specific tasks. Added guidelines of how to use Git, GitHub, and
 
157
      how to use pull request together with Trac instead.
 
158
 
 
159
  If the patch wasn't a pull request, you should credit the contributors in
 
160
  the commit message: "Thanks A for report, B for the patch and C for the
 
161
  review."
 
162
 
58
163
* For commits to a branch, prefix the commit message with the branch name.
59
 
  For example: "magic-removal: Added support for mind reading."
 
164
  For example: "[1.4.x] Fixed #xxxxx -- Added support for mind reading."
60
165
 
61
166
* Limit commits to the most granular change that makes sense. This means,
62
167
  use frequent small commits rather than infrequent large commits. For
65
170
  separate commit. This goes a *long way* in helping all core Django
66
171
  developers follow your changes.
67
172
 
68
 
* Separate bug fixes from feature changes.
69
 
 
70
 
  Bug fixes need to be added to the current bugfix branch as well as the
71
 
  current trunk.
 
173
* Separate bug fixes from feature changes. Bugfixes may need to be backported
 
174
  to the stable branch, according to the :ref:`backwards-compatibility policy
 
175
  <backwards-compatibility-policy>`.
72
176
 
73
177
* If your commit closes a ticket in the Django `ticket tracker`_, begin
74
 
  your commit message with the text "Fixed #abc", where "abc" is the
 
178
  your commit message with the text "Fixed #xxxxx", where "xxxxx" is the
75
179
  number of the ticket your commit fixes. Example: "Fixed #123 -- Added
76
 
  support for foo". We've rigged Subversion and Trac so that any commit
77
 
  message in that format will automatically close the referenced ticket
78
 
  and post a comment to it with the full commit message.
 
180
  whizbang feature.". We've rigged Trac so that any commit message in that
 
181
  format will automatically close the referenced ticket and post a comment
 
182
  to it with the full commit message.
79
183
 
80
184
  If your commit closes a ticket and is in a branch, use the branch name
81
 
  first, then the "Fixed #abc." For example:
82
 
  "magic-removal: Fixed #123 -- Added whizbang feature."
83
 
 
84
 
  For the curious: we're using a `Trac post-commit hook`_ for this.
85
 
 
86
 
  .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-svn-post-commit-hook.cmd
 
185
  first, then the "Fixed #xxxxx." For example:
 
186
  "[1.4.x] Fixed #123 -- Added whizbang feature."
 
187
 
 
188
  For the curious, we're using a `Trac plugin`_ for this.
 
189
 
 
190
.. note::
 
191
 
 
192
    Note that the Trac integration doesn't know anything about pull requests.
 
193
    So if you try to close a pull request with the phrase "closes #400" in your
 
194
    commit message, GitHub will close the pull request, but the Trac plugin
 
195
    will also close the same numbered ticket in Trac.
 
196
 
 
197
 
 
198
.. _Trac plugin: https://github.com/aaugustin/trac-github
87
199
 
88
200
* If your commit references a ticket in the Django `ticket tracker`_ but
89
 
  does *not* close the ticket, include the phrase "Refs #abc", where "abc"
90
 
  is the number of the ticket your commit references. We've rigged
91
 
  Subversion and Trac so that any commit message in that format will
92
 
  automatically post a comment to the appropriate ticket.
 
201
  does *not* close the ticket, include the phrase "Refs #xxxxx", where "xxxxx"
 
202
  is the number of the ticket your commit references. This will automatically
 
203
  post a comment to the appropriate ticket.
93
204
 
94
205
* Write commit messages for backports using this pattern::
95
206
 
99
210
 
100
211
  For example::
101
212
 
102
 
    [1.3.X] Fixed #17028 - Changed diveintopython.org -> diveintopython.net.
 
213
    [1.3.x] Fixed #17028 - Changed diveintopython.org -> diveintopython.net.
103
214
 
104
 
    Backport of r17115 from trunk.
 
215
    Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from master.
105
216
 
106
217
Reverting commits
107
218
-----------------
108
219
 
109
 
Nobody's perfect; mistakes will be committed. When a mistaken commit is
110
 
discovered, please follow these guidelines:
111
 
 
112
 
* Try very hard to ensure that mistakes don't happen. Just because we
113
 
  have a reversion policy doesn't relax your responsibility to aim for
114
 
  the highest quality possible. Really: double-check your work before
115
 
  you commit it in the first place!
 
220
Nobody's perfect; mistakes will be committed.
 
221
 
 
222
But try very hard to ensure that mistakes don't happen. Just because we have a
 
223
reversion policy doesn't relax your responsibility to aim for the highest
 
224
quality possible. Really: double-check your work, or have it checked by
 
225
another committer, **before** you commit it in the first place!
 
226
 
 
227
When a mistaken commit is discovered, please follow these guidelines:
116
228
 
117
229
* If possible, have the original author revert his/her own commit.
118
230
 
119
231
* Don't revert another author's changes without permission from the
120
232
  original author.
121
233
 
 
234
* Use git revert -- this will make a reverse commit, but the original
 
235
  commit will still be part of the commit history.
 
236
 
122
237
* If the original author can't be reached (within a reasonable amount
123
238
  of time -- a day or so) and the problem is severe -- crashing bug,
124
239
  major test failures, etc -- then ask for objections on the
139
254
* The release branch maintainer may back out commits to the release
140
255
  branch without permission if the commit breaks the release branch.
141
256
 
 
257
* If you mistakenly push a topic branch to django/django, just delete it.
 
258
  For instance, if you did: ``git push upstream feature_antigravity``,
 
259
  just do a reverse push: ``git push upstream :feature_antigravity``.
 
260
 
142
261
.. _django-developers: http://groups.google.com/group/django-developers
143
262
.. _ticket tracker: https://code.djangoproject.com/newticket