Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Proof-read the new contributing guide.

Many thanks to Daniele Procida.
  • Loading branch information...
commit 329bb9296f402c6e7d7b648937b72b13a6f5756c 1 parent 23d230f
Aymeric Augustin authored
1  AUTHORS
@@ -425,6 +425,7 @@ answer newbie questions, and generally made Django that much better:
425 425
     polpak@yahoo.com
426 426
     Ross Poulton <ross@rossp.org>
427 427
     Mihai Preda <mihai_preda@yahoo.com>
  428
+    Daniele Procida <daniele@vurt.org>
428 429
     Matthias Pronk <django@masida.nl>
429 430
     Jyrki Pulliainen <jyrki.pulliainen@gmail.com>
430 431
     Thejaswi Puthraya <thejaswi.puthraya@gmail.com>
53  docs/internals/contributing/committing-code.txt
@@ -21,7 +21,7 @@ Partial committers
21 21
     access to the subsystems that fall under their jurisdiction, and they're
22 22
     given a formal vote in questions that involve their subsystems. This type
23 23
     of access is likely to be given to someone who contributes a large
24  
-    subframework to Django and wants to continue to maintain it.
  24
+    sub-framework to Django and wants to continue to maintain it.
25 25
 
26 26
     Partial commit access is granted by the same process as full
27 27
     committers. However, the bar is set lower; proven expertise in the area
@@ -30,26 +30,28 @@ Partial committers
30 30
 Decisions on new committers will follow the process explained in
31 31
 :ref:`how-we-make-decisions`. To request commit access, please contact an
32 32
 existing committer privately. Public requests for commit access are potential
33  
-flame-war starters, and will be ignored.
  33
+flame-war starters, and will simply be ignored.
34 34
 
35 35
 Handling pull requests
36 36
 ----------------------
37 37
 
38 38
 Since Django is now hosted at GitHub, many patches are provided in the form of
39  
-pull requests. When committing a pull request, make sure each individual
40  
-commit matches the commit guidelines described below. Contributors are
41  
-expected to provide the best pull requests possible. However, in practice,
42  
-committers are more familiar with the commit guidelines, and they may have to
43  
-rewrite the commit history.
  39
+pull requests.
  40
+
  41
+When committing a pull request, make sure each individual commit matches the
  42
+commit guidelines described below. Contributors are expected to provide the
  43
+best pull requests possible. In practice however, committers - who will likely
  44
+be more familiar with the commit guidelines - may decide to bring a commit up
  45
+to standard themselves.
44 46
 
45 47
 Here is one way to commit a pull request::
46 48
 
47 49
     # Create a new branch tracking upstream/master -- upstream is assumed
48 50
     # to be django/django.
49  
-    git checkout -b pull_xxxx upstream/master
  51
+    git checkout -b pull_xxxxx upstream/master
50 52
 
51 53
     # Download the patches from github and apply them.
52  
-    curl https://github.com/django/django/pull/XXXX.patch | git am
  54
+    curl https://github.com/django/django/pull/xxxxx.patch | git am
53 55
 
54 56
 At this point, you can work on the code. Use ``git rebase -i`` and ``git
55 57
 commit --amend`` to make sure the commits have the expected level of quality.
@@ -59,20 +61,20 @@ Once you're ready::
59 61
     git checkout master
60 62
     git pull upstream master
61 63
     # Merge the work as "fast-forward" to master, to avoid a merge commit.
62  
-    git merge --ff-only pull_xx
  64
+    git merge --ff-only pull_xxxxx
63 65
     # Check that only the changes you expect will be pushed to upstream.
64 66
     git push --dry-run upstream master
65 67
     # Push!
66 68
     git push upstream master
67 69
 
68  
-    # Get rid of the pull_xxxx branch.
69  
-    git branch -d pull_xxxx
  70
+    # Get rid of the pull_xxxxx branch.
  71
+    git branch -d pull_xxxxx
70 72
 
71  
-An alternative is to add the contributor's repository as a new remote, do a
72  
-checkout of the branch and work from there::
  73
+An alternative is to add the contributor's repository as a new remote,
  74
+checkout the branch and work from there::
73 75
 
74 76
     git remote add <contributor> https://github.com/<contributor>/django.git
75  
-    git checkout pull_xxxx <contributor> <contributor's pull request branch>
  77
+    git checkout pull_xxxxx <contributor> <contributor's pull request branch>
76 78
 
77 79
 At this point, you can work on the code and continue as above.
78 80
 
@@ -151,7 +153,7 @@ Django's Git repository:
151 153
   review."
152 154
 
153 155
 * For commits to a branch, prefix the commit message with the branch name.
154  
-  For example: "[1.4.x] Fixed #NNNNN -- Added support for mind reading."
  156
+  For example: "[1.4.x] Fixed #xxxxx -- Added support for mind reading."
155 157
 
156 158
 * Limit commits to the most granular change that makes sense. This means,
157 159
   use frequent small commits rather than infrequent large commits. For
@@ -165,14 +167,14 @@ Django's Git repository:
165 167
   <backwards-compatibility-policy>`.
166 168
 
167 169
 * If your commit closes a ticket in the Django `ticket tracker`_, begin
168  
-  your commit message with the text "Fixed #NNNNN", where "NNNNN" is the
  170
+  your commit message with the text "Fixed #xxxxx", where "xxxxx" is the
169 171
   number of the ticket your commit fixes. Example: "Fixed #123 -- Added
170 172
   whizbang feature.". We've rigged Trac so that any commit message in that
171 173
   format will automatically close the referenced ticket and post a comment
172 174
   to it with the full commit message.
173 175
 
174 176
   If your commit closes a ticket and is in a branch, use the branch name
175  
-  first, then the "Fixed #NNNNN." For example:
  177
+  first, then the "Fixed #xxxxx." For example:
176 178
   "[1.4.x] Fixed #123 -- Added whizbang feature."
177 179
 
178 180
   For the curious, we're using a `Trac plugin`_ for this.
@@ -180,7 +182,7 @@ Django's Git repository:
180 182
   .. _Trac plugin: https://github.com/aaugustin/trac-github
181 183
 
182 184
 * If your commit references a ticket in the Django `ticket tracker`_ but
183  
-  does *not* close the ticket, include the phrase "Refs #NNNNN", where "NNNNN"
  185
+  does *not* close the ticket, include the phrase "Refs #xxxxx", where "xxxxx"
184 186
   is the number of the ticket your commit references. This will automatically
185 187
   post a comment to the appropriate ticket.
186 188
 
@@ -199,13 +201,14 @@ Django's Git repository:
199 201
 Reverting commits
200 202
 -----------------
201 203
 
202  
-Nobody's perfect; mistakes will be committed. When a mistaken commit is
203  
-discovered, please follow these guidelines:
  204
+Nobody's perfect; mistakes will be committed.
  205
+
  206
+But try very hard to ensure that mistakes don't happen. Just because we have a
  207
+reversion policy doesn't relax your responsibility to aim for the highest
  208
+quality possible. Really: double-check your work, or have it checked by
  209
+another committer, **before** you commit it in the first place!
204 210
 
205  
-* Try very hard to ensure that mistakes don't happen. Just because we
206  
-  have a reversion policy doesn't relax your responsibility to aim for
207  
-  the highest quality possible. Really: double-check your work, or have
208  
-  it checked by another committer, before you commit it in the first place!
  211
+When a mistaken commit is discovered, please follow these guidelines:
209 212
 
210 213
 * If possible, have the original author revert his/her own commit.
211 214
 
46  docs/internals/contributing/writing-code/submitting-patches.txt
@@ -20,9 +20,10 @@ See the :doc:`working-with-git` for more details on how to use pull requests.
20 20
 
21 21
 In an open-source project with hundreds of contributors around the world, it's
22 22
 important to manage communication efficiently so that work doesn't get
23  
-duplicated and contributors can be as effective as possible. Hence, our policy
24  
-is for contributors to "claim" tickets in order to let other developers know
25  
-that a particular bug or feature is being worked on.
  23
+duplicated and contributors can be as effective as possible.
  24
+
  25
+Hence, our policy is for contributors to "claim" tickets in order to let other
  26
+developers know that a particular bug or feature is being worked on.
26 27
 
27 28
 If you have identified a contribution you want to make and you're capable of
28 29
 fixing it (as measured by your coding ability, knowledge of Django internals
@@ -68,18 +69,23 @@ no longer monopolized and somebody else can claim it.
68 69
 If you've claimed a ticket and it's taking a long time (days or weeks) to code,
69 70
 keep everybody updated by posting comments on the ticket. If you don't provide
70 71
 regular updates, and you don't respond to a request for a progress report,
71  
-your claim on the ticket may be revoked. As always, more communication is
72  
-better than less communication!
  72
+your claim on the ticket may be revoked.
  73
+
  74
+As always, more communication is better than less communication!
73 75
 
74 76
 Which tickets should be claimed?
75 77
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76 78
 
77 79
 Of course, going through the steps of claiming tickets is overkill in some
78  
-cases. In the case of small changes, such as typos in the documentation or
  80
+cases.
  81
+
  82
+In the case of small changes, such as typos in the documentation or
79 83
 small bugs that will only take a few minutes to fix, you don't need to jump
80 84
 through the hoops of claiming tickets. Just submit your patch and be done with
81  
-it. Of course, it is always acceptable, regardless of the ticket's ownership
82  
-status, to submit patches to a ticket if you happen to have a patch ready.
  85
+it.
  86
+
  87
+Of course, it is *always* acceptable, regardless whether someone has claimed it
  88
+or not, to submit patches to a ticket if you happen to have a patch ready.
83 89
 
84 90
 .. _patch-style:
85 91
 
@@ -90,12 +96,12 @@ Make sure that any contribution you do fulfills at least the following
90 96
 requirements:
91 97
 
92 98
 * The code required to fix a problem or add a feature is an essential part
93  
-  of a patch, but it is not the only part. A good patch should also
94  
-  include a regression test to validate the behavior that has been fixed
95  
-  and to prevent the problem from arising again. Also, if some tickets are
96  
-  relevant to the code that you've written, mention the ticket numbers in
  99
+  of a patch, but it is not the only part. A good patch should also include a
  100
+  :doc:`regression test <unit-tests>` to validate the behavior that has been
  101
+  fixed and to prevent the problem from arising again. Also, if some tickets
  102
+  are relevant to the code that you've written, mention the ticket numbers in
97 103
   some comments in the test so that one can easily trace back the relevant
98  
-  discussions after your patch gets committed and the tickets get closed.
  104
+  discussions after your patch gets committed, and the tickets get closed.
99 105
 
100 106
 * If the code associated with a patch adds a new feature, or modifies
101 107
   behavior of an existing feature, the patch should also contain
@@ -105,6 +111,7 @@ You can use either GitHub branches and pull requests or direct patches
105 111
 to publish your work. If you use the Git workflow, then you should
106 112
 announce your branch in the ticket by including a link to your branch.
107 113
 When you think your work is ready to be merged in create a pull request.
  114
+
108 115
 See the :doc:`working-with-git` documentation for mode details.
109 116
 
110 117
 You can also use patches in Trac. When using this style, follow these
@@ -139,8 +146,10 @@ A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
139 146
 that introduces Django functionality and makes some sort of design decision.
140 147
 
141 148
 If you provide a non-trivial patch, include evidence that alternatives have
142  
-been discussed on `django-developers`_. If you're not sure whether your patch
143  
-should be considered non-trivial, just ask.
  149
+been discussed on `django-developers`_.
  150
+
  151
+If you're not sure whether your patch should be considered non-trivial, just
  152
+ask.
144 153
 
145 154
 Javascript patches
146 155
 ------------------
@@ -156,6 +165,9 @@ code for future development (e.g. ``foo.js``), and a compressed version for
156 165
 production use (e.g. ``foo.min.js``). Any links to the file in the codebase
157 166
 should point to the compressed version.
158 167
 
  168
+Compressing JavaScript
  169
+~~~~~~~~~~~~~~~~~~~~~~
  170
+
159 171
 To simplify the process of providing optimized javascript code, Django
160 172
 includes a handy script which should be used to create a "minified" version.
161 173
 This script is located at ``django/contrib/admin/static/js/compress.py``.
@@ -167,11 +179,11 @@ complete javascript patches will need to download and install the library
167 179
 independently.
168 180
 
169 181
 The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
170  
-higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with
  182
+higher on Mac OS X. Note that Mac OS X 10.5 and earlier did not ship with
171 183
 Java 1.6 by default, so it may be necessary to upgrade your Java installation
172 184
 before the tool will be functional. Also note that even after upgrading Java,
173 185
 the default ``/usr/bin/java`` command may remain linked to the previous Java
174  
-binary, so relinking that command may be necessary as well.
  186
+binary, so relinking that command may be necessary as well.)
175 187
 
176 188
 Please don't forget to run ``compress.py`` and include the ``diff`` of the
177 189
 minified scripts when submitting patches for Django's javascript.
178  docs/internals/contributing/writing-code/working-with-git.txt
@@ -11,18 +11,20 @@ that you also work using GitHub.
11 11
 After installing Git the first thing you should do is setup your name and
12 12
 email::
13 13
 
14  
-  $ git config --global user.name "Firstname Lastname"
15  
-  $ git config --global user.email "your_email@youremail.com"
  14
+  $ git config --global user.name "Your Real Name"
  15
+  $ git config --global user.email "you@email.com"
16 16
 
17 17
 Note that ``user.name`` should be your real name, not your GitHub nick. GitHub
18 18
 should know the email you use in the ``user.email`` field, as this will be
19 19
 used to associate your commits with your GitHub account.
20 20
 
21 21
 Now we are going to show how to create a GitHub pull request containing the
22  
-changes for Trac ticket #xxxxx. By creating a fully ready pull request you
23  
-will make the committers' job easier, and thus your work is more likely to be
24  
-merged into Django. You can also upload a traditional patch to Trac, but it's
25  
-less practical for reviews.
  22
+changes for Trac ticket #xxxxx. By creating a fully-ready pull request you
  23
+will make the committers' job easier, meaning that your work is more likely to
  24
+be merged into Django.
  25
+
  26
+You could also upload a traditional patch to Trac, but it's less practical for
  27
+reviews.
26 28
 
27 29
 .. _Git: http://git-scm.com/
28 30
 .. _GitHub: https://github.com/
@@ -31,14 +33,18 @@ less practical for reviews.
31 33
 Setting up local repository
32 34
 ---------------------------
33 35
 
34  
-When you have created a GitHub account, with the nick "github_nick", and
35  
-forked Django's repository, you should create a local copy of your fork::
  36
+When you have created your GitHub account, with the nick "github_nick", and
  37
+forked Django's repository, create a local copy of your fork::
36 38
 
37 39
     git clone git@github.com:github_nick/django.git
38 40
 
39  
-This will create a new directory "django" containing a clone of your GitHub
40  
-repository. Your GitHub repository will be called "origin" in Git. You should
41  
-also setup django/django as an "upstream" remote::
  41
+This will create a new directory "django", containing a clone of your GitHub
  42
+repository.
  43
+
  44
+Your GitHub repository will be called "origin" in Git.
  45
+
  46
+You should also setup django/django as an "upstream" remote (that is, tell git
  47
+that the reference Django repository was the source of your fork of it)::
42 48
 
43 49
     git remote add upstream git@github.com:django/django.git
44 50
     git fetch upstream
@@ -50,12 +56,15 @@ You can add other remotes similarly, for example::
50 56
 Working on a ticket
51 57
 -------------------
52 58
 
53  
-When working on a ticket you will almost always want to create a new branch
54  
-for the work, and base that work on upstream/master::
  59
+When working on a ticket create a new branch for the work, and base that work
  60
+on upstream/master::
55 61
 
56 62
     git checkout -b ticket_xxxxx upstream/master
57 63
 
58  
-If you are working for a fix on the 1.4 branch, you would instead do::
  64
+The -b flag creates a new branch for you locally. Don't hesitate to create new
  65
+branches even for the smallest things - that's what they are there for.
  66
+
  67
+If instead you were working for a fix on the 1.4 branch, you would do::
59 68
 
60 69
     git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x
61 70
 
@@ -64,7 +73,7 @@ commit them::
64 73
 
65 74
     git commit
66 75
 
67  
-When writing the commit message, you should follow the :ref:`commit message
  76
+When writing the commit message, follow the :ref:`commit message
68 77
 guidelines <committing-guidlines>` to ease the work of the committer. If
69 78
 you're uncomfortable with English, try at least to describe precisely what the
70 79
 commit does.
@@ -77,69 +86,77 @@ necessary::
77 86
 Publishing work
78 87
 ~~~~~~~~~~~~~~~
79 88
 
80  
-You can publish your work on GitHub by just using::
  89
+You can publish your work on GitHub just by doing::
81 90
 
82 91
   git push origin ticket_xxxxx
83 92
 
84 93
 When you go to your GitHub page you will notice a new branch has been created.
  94
+
85 95
 If you are working on a Trac ticket, you should mention in the ticket that
86 96
 your work is available from branch ticket_xxxxx of your github repo. Include a
87 97
 link to your branch.
88 98
 
89  
-Note that the above branch is called a "topic branch" in Git parlance. This
90  
-means that other people should not base their work on your branch. In
91  
-particular this means you are free to rewrite the history of this branch (by
92  
-using ``git rebase`` for example). There are also "public branches". These are
93  
-branches other people are supposed to fork, and thus their history should
94  
-never change. Good examples of public branches are the ``master`` and
95  
-``stable/A.B.x`` branches in the django/django repository.
  99
+Note that the above branch is called a "topic branch" in Git parlance. You are
  100
+free to rewrite the history of this branch, by using ``git rebase`` for
  101
+example. Other people shouldn't base their work on such a branch, because
  102
+their clone would become corrupt when you edit commits.
  103
+
  104
+There are also "public branches". These are branches other people are supposed
  105
+to fork, so the history of these branches should never change. Good examples
  106
+of public branches are the ``master`` and ``stable/A.B.x`` branches in the
  107
+django/django repository.
96 108
 
97 109
 When you think your work is ready to be pulled into Django, you should create
98  
-a pull request at GitHub. A good pull request contains:
  110
+a pull request at GitHub. A good pull request means:
99 111
 
100  
-* Commits with one logical change in each, following the
101  
-  :doc:`coding style <coding-style>`.
  112
+* commits with one logical change in each, following the
  113
+  :doc:`coding style <coding-style>`,
102 114
 
103  
-* Well formed messages for each commit: a summary line and then paragraphs
104  
-  wrapped at 72 characters thereafter. See the :ref:`committing guidelines
105  
-  <committing-guidlines>` for more details.
  115
+* well-formed messages for each commit: a summary line and then paragraphs
  116
+  wrapped at 72 characters thereafter -- see the :ref:`committing guidelines
  117
+  <committing-guidlines>` for more details,
106 118
 
107  
-* Documentation and tests, if needed. Actually tests are always needed, except
108  
-  for documentation changes.
  119
+* documentation and tests, if needed -- actually tests are always needed,
  120
+  except for documentation changes.
109 121
 
110  
-* The test suite passes and the documentation builds without warnings.
  122
+The test suite must pass and the documentation must build without warnings.
111 123
 
112 124
 Once you have created your pull request, you should add a comment in the
113  
-related Trac ticket explaining what you've done. In particular you should tell
114  
-in which environment you've run the tests, for instance: "all tests pass under
115  
-SQLite and MySQL".
  125
+related Trac ticket explaining what you've done. In particular you should note
  126
+the environment in which you ran the tests, for instance: "all tests pass
  127
+under SQLite and MySQL".
116 128
 
117  
-Your pull request should be ready for merging into Django. Pull requests at
118  
-GitHub have only two states: open and closed. The committers who deals with
119  
-your pull request has only two options: merge it or close it. For this reason,
120  
-it isn't useful to make a pull request until the code is ready for merging --
121  
-or sufficiently close that a committer will finish it himself.
  129
+Pull requests at GitHub have only two states: open and closed. The committer
  130
+who will deal with your pull request has only two options: merge it or close
  131
+it. For this reason, it isn't useful to make a pull request until the code is
  132
+ready for merging -- or sufficiently close that a committer will finish it
  133
+himself.
122 134
 
123 135
 Rebasing branches
124 136
 ~~~~~~~~~~~~~~~~~
125 137
 
126 138
 In the example above you created two commits, the "Fixed ticket_xxxxx" commit
127  
-and "Added two more tests" commit. We do not want to have the "Added two more
128  
-tests" commit in the Django's repository as it would just be useless noise.
129  
-Instead, we would like to only have one commit. To rework the history of your
130  
-branch you can squash the commits into one by using interactive rebase::
  139
+and "Added two more tests" commit.
  140
+
  141
+We do not want to have the entire history of your working process in your
  142
+repository. Your commit "Added two more tests" would be unhelpful noise.
  143
+Instead, we would rather only have one commit containing all your work.
  144
+
  145
+To rework the history of your branch you can squash the commits into one by
  146
+using interactive rebase::
131 147
 
132 148
     git rebase -i HEAD~2
133 149
 
134 150
 The HEAD~2 above is shorthand for two latest commits. The above command
135 151
 will open an editor showing the two commits, prefixed with the word "pick".
136  
-You should change the second line to "squash" instead. This will keep the
137  
-first commit, and squash the second commit to the first one. Save and quit
138  
-the editor. A second editor window should open. Here you can reword the
139  
-commit message for the commit.
  152
+
  153
+Change the second line to "squash" instead. This will keep the
  154
+first commit, and squash the second commit into the first one. Save and quit
  155
+the editor. A second editor window should open, so you can reword the
  156
+commit message for the commit now that it includes both your steps.
140 157
 
141 158
 You can also use the "edit" option in rebase. This way you can change a single
142  
-commit. For example::
  159
+commit, for example to fix a typo in a docstring::
143 160
 
144 161
     git rebase -i HEAD~3
145 162
     # Choose edit, pick, pick for the commits
@@ -148,17 +165,18 @@ commit. For example::
148 165
     git commit --amend
149 166
     # reword the commit message if needed
150 167
     git rebase --continue
151  
-    # The second and third commit should be applied.
  168
+    # The second and third commits should be applied.
152 169
 
153  
-If you need to change an already published topic branch at GitHub, you will
154  
-need to force-push the changes::
  170
+If your topic branch is already published at GitHub, for example if you're
  171
+making minor changes to take into account a review, you will need to force-
  172
+push the changes::
155 173
 
156 174
     git push -f origin ticket_xxxxx
157 175
 
158 176
 Note that this will rewrite history of ticket_xxxxx - if you check the commit
159 177
 hashes before and after the operation at GitHub you will notice that the
160  
-commit hashes do not match any more. This is acceptable, as the branch is topic
161  
-branch, and nobody should be basing their work on this branch.
  178
+commit hashes do not match any more. This is acceptable, as the branch is merely
  179
+a topic branch, and nobody should be basing their work on it.
162 180
 
163 181
 After upstream has changed
164 182
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -173,16 +191,18 @@ The work is automatically rebased using the branch you forked on, in the
173 191
 example case using upstream/master.
174 192
 
175 193
 The rebase command removes all your local commits temporarily, applies the
176  
-upstream commits, and then applies your local commits again on the work. If
177  
-there are merge conflicts you will need to resolve them and then use ``git
  194
+upstream commits, and then applies your local commits again on the work.
  195
+
  196
+If there are merge conflicts you will need to resolve them and then use ``git
178 197
 rebase --continue``. At any point you can use ``git rebase --abort`` to return
179 198
 to the original state.
180 199
 
181  
-Note that you want to rebase on upstream, not merge the upstream. The reason
182  
-for this is that by rebasing, your commits will always be on top of the
183  
-upstream's work, not mixed with the changes in the upstream. This way your
184  
-branch only contains commits related to its topic, and this makes squashing
185  
-easier.
  200
+Note that you want to *rebase* on upstream, not *merge* the upstream.
  201
+
  202
+The reason for this is that by rebasing, your commits will always be *on
  203
+top of* the upstream's work, not *mixed in with* the changes in the upstream.
  204
+This way your branch will contain only commits related to its topic, which
  205
+makes squashing easier.
186 206
 
187 207
 After review
188 208
 ------------
@@ -190,31 +210,35 @@ After review
190 210
 It is unusual to get any non-trivial amount of code into core without changes
191 211
 requested by reviewers. In this case, it is often a good idea to add the
192 212
 changes as one incremental commit to your work. This allows the reviewer to
193  
-easily check what changes you have done::
  213
+easily check what changes you have done.
194 214
 
195  
-  # Do changes required by the reviewer, commit often.
196  
-  # Before publishing the changes, rebase your work. Assume you added two
197  
-  # commits to the work.
198  
-  git rebase -i HEAD~2
199  
-  # squash the second commit into the first, write a commit message something
200  
-  # like this:
201  
-  Made changes asked in review by the_reviewer
  215
+In this case, do the changes required by the reviewer. Commit as often as
  216
+necessary. Before publishing the changes, rebase your work. If you added two
  217
+commits, you would run::
202 218
 
203  
-    - Fixed whitespace errors in foo/bar
204  
-    - Reworded the doc string of the_method()
  219
+    git rebase -i HEAD~2
205 220
 
206  
-  # Push your work back to your github repo, there should not be any need
207  
-  # for force (-f) push, as you didn't touch the public commits in the rebase.
208  
-  git push origin ticket_xxxxx
209  
-  # Check your pull request, it should now contain the new commit, too.
  221
+Squash the second commit into the first. Write a commit message along the lines of::
  222
+
  223
+    Made changes asked in review by <reviewer>
  224
+
  225
+    - Fixed whitespace errors in foobar
  226
+    - Reworded the docstring of bar()
  227
+
  228
+Finally push your work back to your GitHub repository. Since you didn't touch
  229
+the public commits during the rebase, you should not need to force-push::
  230
+
  231
+    git push origin ticket_xxxxx
  232
+
  233
+Your pull request should now contain the new commit too.
210 234
 
211  
-The committer is likely to squash the review commit into the previous commit
  235
+Note that the committer is likely to squash the review commit into the previous commit
212 236
 when committing the code.
213 237
 
214 238
 Summary
215 239
 -------
216 240
 
217  
-* Work on GitHub if possible.
  241
+* Work on GitHub if you can.
218 242
 * Announce your work on the Trac ticket by linking to your GitHub branch.
219 243
 * When you have something ready, make a pull request.
220 244
 * Make your pull requests as good as you can.
58  docs/internals/git.txt
@@ -4,10 +4,13 @@ The Django source code repository
4 4
 
5 5
 When deploying a Django application into a real production environment, you
6 6
 will almost always want to use `an official packaged release of Django`_.
  7
+
7 8
 However, if you'd like to try out in-development code from an upcoming release
8 9
 or contribute to the development of Django, you'll need to obtain a clone of
9  
-Django's source code repository. This document covers the way the code
10  
-repository is laid out and how to work with and find things in it.
  10
+Django's source code repository.
  11
+
  12
+This document covers the way the code repository is laid out and how to work
  13
+with and find things in it.
11 14
 
12 15
 .. _an official packaged release of Django: https://www.djangoproject.com/download/
13 16
 
@@ -17,12 +20,14 @@ High-level overview
17 20
 The Django source code repository uses `Git`_ to track changes to the code
18 21
 over time, so you'll need a copy of the Git client (a program called ``git``)
19 22
 on your computer, and you'll want to familiarize yourself with the basics of
20  
-how Git works. Git's web site offers downloads for various operating systems.
21  
-The site contains also vast amounts of `documentation`_.
  23
+how Git works.
  24
+
  25
+Git's web site offers downloads for various operating systems. The site also
  26
+contains vast amounts of `documentation`_.
22 27
 
23 28
 The Django Git repository is located online at `github.com/django/django
24  
-<https://github.com/django/django>`_. It contains the full source
25  
-code for all Django releases, and you can browse it online.
  29
+<https://github.com/django/django>`_. It contains the full source code for all
  30
+Django releases, which you can browse online.
26 31
 
27 32
 The Git repository includes several `branches`_:
28 33
 
@@ -39,11 +44,10 @@ The Git repository includes several `branches`_:
39 44
 * ``attic/<project>`` branches were used to develop major or experimental new
40 45
   features without affecting the rest of Django's code.
41 46
 
42  
-The Git repository also contains `tags`_. They identify snapshots of Django's
43  
-code at various important points in its history. Mostly these are the exact
44  
-revisions from which packaged Django releases were produced.
  47
+The Git repository also contains `tags`_. These are the exact revisions from
  48
+which packaged Django releases were produced, since version 1.0.
45 49
 
46  
-The source code for `Djangoproject.com <https://www.djangoproject.com/>`_ Web
  50
+The source code for the `Djangoproject.com <https://www.djangoproject.com/>`_ web
47 51
 site can be found at `github.com/django/djangoproject.com
48 52
 <https://github.com/django/djangoproject.com>`_.
49 53
 
@@ -52,8 +56,8 @@ site can be found at `github.com/django/djangoproject.com
52 56
 .. _branches: https://github.com/django/django/branches
53 57
 .. _tags: https://github.com/django/django/tags
54 58
 
55  
-Working with Django's master branch
56  
-===================================
  59
+The master branch
  60
+=================
57 61
 
58 62
 If you'd like to try out the in-development code for the next release of
59 63
 Django, or if you'd like to contribute to Django by fixing bugs or developing
@@ -76,15 +80,15 @@ over to :doc:`the documentation for contributing to Django
76 80
 </internals/contributing/index>`, which covers things like the preferred
77 81
 coding style and how to generate and submit a patch.
78 82
 
79  
-Branches
80  
-========
  83
+Other branches
  84
+==============
81 85
 
82 86
 Django uses branches for two main purposes:
83 87
 
84 88
 1. Development of major or experimental features, to keep them from
85 89
    affecting progress on other work in master.
86 90
 
87  
-2. Security and bug-fix support for older releases of Django, during
  91
+2. Security and bugfix support for older releases of Django, during
88 92
    their support lifetimes.
89 93
 
90 94
 Feature-development branches
@@ -154,9 +158,10 @@ part of Django itself, and so are no longer separately maintained:
154 158
 
155 159
 When Django moved from SVN to Git, the information about branch merges wasn't
156 160
 preserved in the source code repository. This means that the ``master`` branch
157  
-of Django doesn't contain merge commits for the above branches. However, this
158  
-information is `available as a grafts file`_. You can restore it by putting
159  
-the following lines in ``.git/info/grafts`` in your local clone::
  161
+of Django doesn't contain merge commits for the above branches.
  162
+
  163
+However, this information is `available as a grafts file`_. You can restore it
  164
+by putting the following lines in ``.git/info/grafts`` in your local clone::
160 165
 
161 166
   ac64e91a0cadc57f4bc5cd5d66955832320ca7a1 553a20075e6991e7a60baee51ea68c8adc520d9a 0cb8e31823b2e9f05c4ae868c19f5f38e78a5f2e
162 167
   79e68c225b926302ebb29c808dda8afa49856f5c d0f57e7c7385a112cb9e19d314352fc5ed5b0747 aa239e3e5405933af6a29dac3cf587b59a099927
@@ -202,15 +207,18 @@ Support and bugfix branches
202 207
 ---------------------------
203 208
 
204 209
 In addition to fixing bugs in current master, the Django project provides
205  
-official bug-fix support for the most recent released version of Django, and
206  
-security support for the two most recently-released versions of Django. This
207  
-support is provided via branches in which the necessary bug or security fixes
208  
-are applied; the branches are then used as the basis for issuing bugfix or
209  
-security releases.
  210
+official bugfix support for the most recent released version of Django, and
  211
+security support for the two most recently-released versions of Django.
  212
+
  213
+This support is provided via branches in which the necessary bug or security
  214
+fixes are applied; the branches are then used as the basis for issuing bugfix
  215
+or security releases.
210 216
 
211 217
 These branches can be found in the repository as ``stable/A.B.x``
212 218
 branches, and new branches will be created there after each new Django
213  
-release. For example, shortly after the release of Django 1.0, the branch
  219
+release.
  220
+
  221
+For example, shortly after the release of Django 1.0, the branch
214 222
 ``stable/1.0.x`` was created to receive bug fixes, and shortly after the
215 223
 release of Django 1.1 the branch ``stable/1.1.x`` was created.
216 224
 
@@ -222,7 +230,7 @@ used them to provide unofficial support for old Django releases.
222 230
 Tags
223 231
 ====
224 232
 
225  
-Each Django release is tagged and signed by Django's release manage.
  233
+Each Django release is tagged and signed by Django's release manager.
226 234
 
227 235
 The tags can be found on GitHub's `tags`_ page.
228 236
 
10  docs/internals/release-process.txt
@@ -198,15 +198,15 @@ and an rc complete with string freeze two weeks before the end of the schedule.
198 198
 Bug-fix releases
199 199
 ----------------
200 200
 
201  
-After a minor release (e.g. 1.1), the previous release will go into bug-fix
  201
+After a minor release (e.g. 1.1), the previous release will go into bugfix
202 202
 mode.
203 203
 
204 204
 A branch will be created of the form ``branches/releases/1.0.X`` to track
205  
-bug-fixes to the previous release. Critical bugs fixed on trunk must
206  
-*also* be fixed on the bug-fix branch; this means that commits need to cleanly
  205
+bugfixes to the previous release. Critical bugs fixed on trunk must
  206
+*also* be fixed on the bugfix branch; this means that commits need to cleanly
207 207
 separate bug fixes from feature additions. The developer who commits a fix to
208  
-trunk will be responsible for also applying the fix to the current bug-fix
209  
-branch.  Each bug-fix branch will have a maintainer who will work with the
  208
+trunk will be responsible for also applying the fix to the current bugfix
  209
+branch.  Each bugfix branch will have a maintainer who will work with the
210 210
 committers to keep them honest on backporting bug fixes.
211 211
 
212 212
 How this all fits together
2  docs/releases/1.0-beta-2.txt
@@ -69,7 +69,7 @@ the remaining features to be implemented for Django 1.0, and on the
69 69
 bugs that need to be resolved before the final release. As of this
70 70
 beta release, Django is in its final "feature freeze" for 1.0; feature
71 71
 requests will be deferred to later releases, and the development
72  
-effort will be focused solely on bug-fixing and stability. Django is
  72
+effort will be focused solely on bugfixing and stability. Django is
73 73
 also now in a "string freeze"; translatable strings (labels, error
74 74
 messages, etc.) in Django's codebase will not be changed prior to the
75 75
 release, in order to allow our translators to produce the final 1.0
2  docs/releases/1.3.txt
@@ -830,7 +830,7 @@ now pending deprecation.
830 830
 ~~~~~~~~~~~~~~~~
831 831
 
832 832
 Previously, ``django.http`` exposed an undocumented ``CompatCookie`` class,
833  
-which was a bug-fix wrapper around the standard library ``SimpleCookie``. As the
  833
+which was a bugfix wrapper around the standard library ``SimpleCookie``. As the
834 834
 fixes are moving upstream, this is now deprecated - you should use ``from
835 835
 django.http import SimpleCookie`` instead.
836 836
 

0 notes on commit 329bb92

Please sign in to comment.
Something went wrong with that request. Please try again.