Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #18436 -- Updated contributing docs for git.

Most of the credit for this large patch goes to Anssi Kääriäinen.
Many thanks to all the people who contributed to the discussion.
  • Loading branch information...
commit 90fb6a46485d4f3c70d3864ab0a0e2f619449d31 1 parent 1a412dd
Aymeric Augustin authored June 07, 2012
2  docs/index.txt
@@ -204,7 +204,7 @@ The Django open-source project
204 204
   :doc:`How to get involved <internals/contributing/index>` |
205 205
   :doc:`The release process <internals/release-process>` |
206 206
   :doc:`Team of committers <internals/committers>` |
207  
-  :doc:`The Django source code repository <internals/svn>`
  207
+  :doc:`The Django source code repository <internals/git>`
208 208
 
209 209
 * **Design philosophies:**
210 210
   :doc:`Overview <misc/design-philosophies>`
5  docs/internals/contributing/bugs-and-features.txt
@@ -149,9 +149,8 @@ description.
149 149
 
150 150
 As with most open-source projects, code talks. If you are willing to write the
151 151
 code for the feature yourself or, even better, if you've already written it,
152  
-it's much more likely to be accepted. If it's a large feature that might need
153  
-multiple developers, we're always happy to give you an experimental branch in
154  
-our repository; see the :doc:`writing-code/branch-policy`.
  152
+it's much more likely to be accepted. Just fork Django on GitHub, create a
  153
+feature branch, and show us your work!
155 154
 
156 155
 See also: :ref:`documenting-new-features`.
157 156
 
146  docs/internals/contributing/committing-code.txt
@@ -32,11 +32,91 @@ Decisions on new committers will follow the process explained in
32 32
 existing committer privately. Public requests for commit access are potential
33 33
 flame-war starters, and will be ignored.
34 34
 
  35
+Handling pull requests
  36
+----------------------
  37
+
  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.
  44
+
  45
+Here is one way to commit a pull request::
  46
+
  47
+    # Create a new branch tracking upstream/master -- upstream is assumed
  48
+    # to be django/django.
  49
+    git checkout -b pull_xxxx upstream/master
  50
+
  51
+    # Download the patches from github and apply them.
  52
+    curl https://github.com/django/django/pull/XXXX.patch | git am
  53
+
  54
+At this point, you can work on the code. Use ``git rebase -i`` and ``git
  55
+commit --amend`` to make sure the commits have the expected level of quality.
  56
+Once you're ready::
  57
+
  58
+    # Make sure master is ready to receive changes.
  59
+    git checkout master
  60
+    git pull upstream master
  61
+    # Merge the work as "fast-forward" to master, to avoid a merge commit.
  62
+    git merge --ff-only pull_xx
  63
+    # Check that only the changes you expect will be pushed to upstream.
  64
+    git push --dry-run upstream master
  65
+    # Push!
  66
+    git push upstream master
  67
+
  68
+    # Get rid of the pull_xxxx branch.
  69
+    git branch -d pull_xxxx
  70
+
  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
+
  74
+    git remote add <contributor> https://github.com/<contributor>/django.git
  75
+    git checkout pull_xxxx <contributor> <contributor's pull request branch>
  76
+
  77
+At this point, you can work on the code and continue as above.
  78
+
  79
+GitHub provides a one-click merge functionality for pull requests. This should
  80
+only be used if the pull request is 100% ready, and you have checked it for
  81
+errors (or trust the request maker enough to skip checks). Currently, it isn't
  82
+possible to control that the tests pass and that the docs build without
  83
+downloading the changes to your developement environment.
  84
+
  85
+When rewriting the commit history of a pull request, the goal is to make
  86
+Django's commit history is as usable as possible:
  87
+
  88
+* If a patch contains back-and-forth commits, then rewrite those into one.
  89
+  Typically, a commit can add some code, and a second commit can fix
  90
+  stylistic issues introduced in the first commit.
  91
+
  92
+* Separate changes to different commits by logical grouping: if you do a
  93
+  stylistic cleanup at the same time you do other changes to a file,
  94
+  separating the changes to two different commits will make reviewing
  95
+  history easier.
  96
+
  97
+* Beware of merges of upstream branches in the pull requests.
  98
+
  99
+* Tests should pass and docs should build after each commit. Neither the
  100
+  tests nor the docs should emit warnings.
  101
+
  102
+* Trivial and small patches usually are best done in one commit. Medium to
  103
+  large work should be split in multiple commits if possible.
  104
+
  105
+Practicality beats purity, so it is up to each committer to decide how much
  106
+history mangling to do for a pull request. The main points are engaging the
  107
+community, getting work done, and having an usable commit history.
  108
+
  109
+.. _committing-guidlines:
  110
+
35 111
 Committing guidelines
36 112
 ---------------------
37 113
 
38  
-Please follow these guidelines when committing code to Django's Subversion
39  
-repository:
  114
+In addition, please follow the following guidelines when committing code to
  115
+Django's Git repository:
  116
+
  117
+* Never change the published history of django/django branches! **Never force-
  118
+  push your changes to django/django.** If you absolutely must (for security
  119
+  reasons for example) first discuss the situation with the core team.
40 120
 
41 121
 * For any medium-to-big changes, where "medium-to-big" is according to
42 122
   your judgment, please bring things up on the `django-developers`_
@@ -55,8 +135,23 @@ repository:
55 135
   * Bad: "Fixes Unicode bug in RSS API."
56 136
   * Bad: "Fixing Unicode bug in RSS API."
57 137
 
  138
+  The commit message should be in lines of 72 chars maximum. There should be
  139
+  a subject line, separated by a blank line and then paragraphs of 72 char
  140
+  lines. The limits are soft. For the subject line, shorter is better. In the
  141
+  body of the commit message more detail is better than less::
  142
+
  143
+      Fixed #18307 -- Added git workflow guidelines
  144
+
  145
+      Refactored the Django's documentation to remove mentions of SVN
  146
+      specific tasks. Added guidelines of how to use Git, GitHub, and
  147
+      how to use pull request together with Trac instead.
  148
+
  149
+  If the patch wasn't a pull request, you should credit the contributors in
  150
+  the commit message: "Thanks A for report, B for the patch and C for the
  151
+  review."
  152
+
58 153
 * For commits to a branch, prefix the commit message with the branch name.
59  
-  For example: "magic-removal: Added support for mind reading."
  154
+  For example: "[1.4.x] Fixed #NNNNN -- Added support for mind reading."
60 155
 
61 156
 * Limit commits to the most granular change that makes sense. This means,
62 157
   use frequent small commits rather than infrequent large commits. For
@@ -65,31 +160,29 @@ repository:
65 160
   separate commit. This goes a *long way* in helping all core Django
66 161
   developers follow your changes.
67 162
 
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.
  163
+* Separate bug fixes from feature changes. Bugfixes may need to be backported
  164
+  to the stable branch, according to the :ref:`backwards-compatibility policy
  165
+  <backwards-compatibility-policy>`.
72 166
 
73 167
 * 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
  168
+  your commit message with the text "Fixed #NNNNN", where "NNNNN" is the
75 169
   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.
  170
+  whizbang feature.". We've rigged Trac so that any commit message in that
  171
+  format will automatically close the referenced ticket and post a comment
  172
+  to it with the full commit message.
79 173
 
80 174
   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."
  175
+  first, then the "Fixed #NNNNN." For example:
  176
+  "[1.4.x] Fixed #123 -- Added whizbang feature."
83 177
 
84  
-  For the curious: we're using a `Trac post-commit hook`_ for this.
  178
+  For the curious, we're using a `Trac plugin`_ for this.
85 179
 
86  
-  .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-svn-post-commit-hook.cmd
  180
+  .. _Trac plugin: https://github.com/aaugustin/trac-github
87 181
 
88 182
 * 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.
  183
+  does *not* close the ticket, include the phrase "Refs #NNNNN", where "NNNNN"
  184
+  is the number of the ticket your commit references. This will automatically
  185
+  post a comment to the appropriate ticket.
93 186
 
94 187
 * Write commit messages for backports using this pattern::
95 188
 
@@ -99,9 +192,9 @@ repository:
99 192
 
100 193
   For example::
101 194
 
102  
-    [1.3.X] Fixed #17028 - Changed diveintopython.org -> diveintopython.net.
  195
+    [1.3.x] Fixed #17028 - Changed diveintopython.org -> diveintopython.net.
103 196
 
104  
-    Backport of r17115 from trunk.
  197
+    Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from trunk.
105 198
 
106 199
 Reverting commits
107 200
 -----------------
@@ -111,14 +204,17 @@ discovered, please follow these guidelines:
111 204
 
112 205
 * Try very hard to ensure that mistakes don't happen. Just because we
113 206
   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!
  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!
116 209
 
117 210
 * If possible, have the original author revert his/her own commit.
118 211
 
119 212
 * Don't revert another author's changes without permission from the
120 213
   original author.
121 214
 
  215
+* Use git revert -- this will make a reverse commit, but the original
  216
+  commit will still be part of the commit history.
  217
+
122 218
 * If the original author can't be reached (within a reasonable amount
123 219
   of time -- a day or so) and the problem is severe -- crashing bug,
124 220
   major test failures, etc -- then ask for objections on the
@@ -139,5 +235,9 @@ discovered, please follow these guidelines:
139 235
 * The release branch maintainer may back out commits to the release
140 236
   branch without permission if the commit breaks the release branch.
141 237
 
  238
+* If you mistakenly push a topic branch to django/django, just delete it.
  239
+  For instance, if you did: ``git push upstream feature_antigravity``,
  240
+  just do a reverse push: ``git push upstream :feature_antigravity``.
  241
+
142 242
 .. _django-developers: http://groups.google.com/group/django-developers
143 243
 .. _ticket tracker: https://code.djangoproject.com/newticket
171  docs/internals/contributing/writing-code/branch-policy.txt
... ...
@@ -1,171 +0,0 @@
1  
-=============
2  
-Branch policy
3  
-=============
4  
-
5  
-In general, the trunk must be kept stable. People should be able to run
6  
-production sites against the trunk at any time. Additionally, commits to trunk
7  
-ought to be as atomic as possible -- smaller changes are better. Thus, large
8  
-feature changes -- that is, changes too large to be encapsulated in a single
9  
-patch, or changes that need multiple eyes on them -- must happen on dedicated
10  
-branches.
11  
-
12  
-This means that if you want to work on a large feature -- anything that would
13  
-take more than a single patch, or requires large-scale refactoring -- you need
14  
-to do it on a feature branch. Our development process recognizes two options
15  
-for feature branches:
16  
-
17  
-1. Feature branches using a distributed revision control system like
18  
-   Git_, Mercurial_, Bazaar_, etc.
19  
-
20  
-   If you're familiar with one of these tools, this is probably your best
21  
-   option since it doesn't require any support or buy-in from the Django
22  
-   core developers.
23  
-
24  
-   However, do keep in mind that Django will continue to use Subversion
25  
-   for the foreseeable future, and this will naturally limit the
26  
-   recognition of your branch. Further, if your branch becomes eligible
27  
-   for merging to trunk you'll need to find a core developer familiar
28  
-   with your DVCS of choice who'll actually perform the merge.
29  
-
30  
-   If you do decided to start a distributed branch of Django and choose to
31  
-   make it public, please add the branch to the `Django branches`_ wiki
32  
-   page.
33  
-
34  
-2. Feature branches using SVN have a higher bar. If you want a branch
35  
-   in SVN itself, you'll need a "mentor" among the :doc:`core committers
36  
-   </internals/committers>`. This person is responsible for actually
37  
-   creating the branch, monitoring your process (see below), and
38  
-   ultimately merging the branch into trunk.
39  
-
40  
-   If you want a feature branch in SVN, you'll need to ask in
41  
-   `django-developers`_ for a mentor.
42  
-
43  
-.. _git: http://git-scm.com/
44  
-.. _mercurial: http://mercurial.selenic.com/
45  
-.. _bazaar: http://bazaar.canonical.com/
46  
-.. _django branches: https://code.djangoproject.com/wiki/DjangoBranches
47  
-
48  
-Branch rules
49  
-------------
50  
-
51  
-We've got a few rules for branches born out of experience with what makes a
52  
-successful Django branch.
53  
-
54  
-DVCS branches are obviously not under central control, so we have no way of
55  
-enforcing these rules. However, if you're using a DVCS, following these rules
56  
-will give you the best chance of having a successful branch (read: merged back
57  
-to trunk).
58  
-
59  
-Developers with branches in SVN, however, **must** follow these rules. The
60  
-branch mentor will keep on eye on the branch and **will delete it** if these
61  
-rules are broken.
62  
-
63  
-* Only branch entire copies of the Django tree, even if work is only
64  
-  happening on part of that tree. This makes it painless to switch to a
65  
-  branch.
66  
-
67  
-* Merge changes from trunk no less than once a week, and preferably every
68  
-  couple-three days.
69  
-
70  
-  In our experience, doing regular trunk merges is often the difference
71  
-  between a successful branch and one that fizzles and dies.
72  
-
73  
-  If you're working on an SVN branch, you should be using `svnmerge.py`_
74  
-  to track merges from trunk.
75  
-
76  
-* Keep tests passing and documentation up-to-date. As with patches,
77  
-  we'll only merge a branch that comes with tests and documentation.
78  
-
79  
-.. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py
80  
-
81  
-Once the branch is stable and ready to be merged into the trunk, alert
82  
-`django-developers`_.
83  
-
84  
-After a branch has been merged, it should be considered "dead"; write access
85  
-to it will be disabled, and old branches will be periodically "trimmed."
86  
-To keep our SVN wrangling to a minimum, we won't be merging from a given
87  
-branch into the trunk more than once.
88  
-
89  
-Using branches
90  
---------------
91  
-
92  
-To use a branch, you'll need to do two things:
93  
-
94  
-* Get the branch's code through Subversion.
95  
-
96  
-* Point your Python ``site-packages`` directory at the branch's version of
97  
-  the ``django`` package rather than the version you already have
98  
-  installed.
99  
-
100  
-Getting the code from Subversion
101  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102  
-
103  
-To get the latest version of a branch's code, check it out using Subversion:
104  
-
105  
-.. code-block:: bash
106  
-
107  
-    svn co https://code.djangoproject.com/svn/django/branches/<branch>/
108  
-
109  
-...where ``<branch>`` is the branch's name. See the `list of branch names`_.
110  
-
111  
-Alternatively, you can automatically convert an existing directory of the
112  
-Django source code as long as you've checked it out via Subversion. To do the
113  
-conversion, execute this command from within your ``django`` directory:
114  
-
115  
-.. code-block:: bash
116  
-
117  
-    svn switch https://code.djangoproject.com/svn/django/branches/<branch>/
118  
-
119  
-The advantage of using ``svn switch`` instead of ``svn co`` is that the
120  
-``switch`` command retains any changes you might have made to your local copy
121  
-of the code. It attempts to merge those changes into the "switched" code. The
122  
-disadvantage is that it may cause conflicts with your local changes if the
123  
-"switched" code has altered the same lines of code.
124  
-
125  
-(Note that if you use ``svn switch``, you don't need to point Python at the
126  
-new version, as explained in the next section.)
127  
-
128  
-.. _list of branch names: https://code.djangoproject.com/browser/django/branches
129  
-
130  
-.. _pointing-python-at-the-new-django-version:
131  
-
132  
-Pointing Python at the new Django version
133  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
134  
-
135  
-Once you've retrieved the branch's code, you'll need to change your Python
136  
-``site-packages`` directory so that it points to the branch version of the
137  
-``django`` directory. (The ``site-packages`` directory is somewhere such as
138  
-``/usr/lib/python2.7/site-packages`` or
139  
-``/usr/local/lib/python2.7/site-packages`` or ``C:\Python\site-packages``.)
140  
-
141  
-The simplest way to do this is by renaming the old ``django`` directory to
142  
-``django.OLD`` and moving the trunk version of the code into the directory
143  
-and calling it ``django``.
144  
-
145  
-Alternatively, you can use a symlink called ``django`` that points to the
146  
-location of the branch's ``django`` package. If you want to switch back, just
147  
-change the symlink to point to the old code.
148  
-
149  
-A third option is to use a path file (``<something>.pth``). This is a feature of
150  
-the :mod:`site` module. First, make sure there are no files, directories or
151  
-symlinks named ``django`` in your ``site-packages`` directory. Then create a
152  
-text file named ``django.pth`` and save it to your ``site-packages`` directory.
153  
-That file should contain a path to your copy of Django on a single line and
154  
-optional comments. Here is an example that points to multiple branches. Just
155  
-uncomment the line for the branch you want to use ('trunk' in this example) and
156  
-make sure all other lines are commented::
157  
-
158  
-    # Trunk is a svn checkout of:
159  
-    #   https://code.djangoproject.com/svn/django/trunk/
160  
-    #
161  
-    /path/to/trunk
162  
-
163  
-    # <branch> is a svn checkout of:
164  
-    #   https://code.djangoproject.com/svn/django/branches/<branch>/
165  
-    #
166  
-    #/path/to/<branch>
167  
-
168  
-    # On windows a path may look like this:
169  
-    # C:/path/to/<branch>
170  
-
171  
-.. _django-developers: http://groups.google.com/group/django-developers
2  docs/internals/contributing/writing-code/index.txt
@@ -12,4 +12,4 @@ chances to be included in Django core:
12 12
    coding-style
13 13
    unit-tests
14 14
    submitting-patches
15  
-   branch-policy
  15
+   working-with-git
60  docs/internals/contributing/writing-code/submitting-patches.txt
@@ -6,6 +6,15 @@ We're always grateful for patches to Django's code. Indeed, bug reports
6 6
 with associated patches will get fixed *far* more quickly than those
7 7
 without patches.
8 8
 
  9
+Typo fixes and trivial documentation changes
  10
+--------------------------------------------
  11
+
  12
+If you are fixing a really trivial issue, for example changing a word in the
  13
+documentation, the preferred way to provide the patch is using GitHub pull
  14
+requests without a Trac ticket. Trac tickets are still acceptable.
  15
+
  16
+See the :doc:`working-with-git` for more details on how to use pull requests.
  17
+
9 18
 "Claiming" tickets
10 19
 ------------------
11 20
 
@@ -69,28 +78,44 @@ Of course, going through the steps of claiming tickets is overkill in some
69 78
 cases. In the case of small changes, such as typos in the documentation or
70 79
 small bugs that will only take a few minutes to fix, you don't need to jump
71 80
 through the hoops of claiming tickets. Just submit your patch and be done with
72  
-it.
  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.
73 83
 
74 84
 .. _patch-style:
75 85
 
76 86
 Patch style
77 87
 -----------
78 88
 
79  
-* Make sure your code matches our :doc:`coding-style`.
  89
+Make sure that any contribution you do fulfills at least the following
  90
+requirements:
  91
+
  92
+* 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
  97
+  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.
  99
+
  100
+* If the code associated with a patch adds a new feature, or modifies
  101
+  behavior of an existing feature, the patch should also contain
  102
+  documentation.
  103
+
  104
+You can use either GitHub branches and pull requests or direct patches
  105
+to publish your work. If you use the Git workflow, then you should
  106
+announce your branch in the ticket by including a link to your branch.
  107
+When you think your work is ready to be merged in create a pull request.
  108
+See the :doc:`working-with-git` documentation for mode details.
80 109
 
81  
-* Submit patches in the format returned by the ``svn diff`` command.
  110
+You can also use patches in Trac. When using this style, follow these
  111
+guidelines.
  112
+
  113
+* Submit patches in the format returned by the ``git diff`` command.
82 114
   An exception is for code changes that are described more clearly in
83 115
   plain English than in code. Indentation is the most common example; it's
84 116
   hard to read patches when the only difference in code is that it's
85 117
   indented.
86 118
 
87  
-  Patches in ``git diff`` format are also acceptable.
88  
-
89  
-* When creating patches, always run ``svn diff`` from the top-level
90  
-  ``trunk`` directory -- i.e. the one that contains ``django``, ``docs``,
91  
-  ``tests``, ``AUTHORS``, etc. This makes it easy for other people to
92  
-  apply your patches.
93  
-
94 119
 * Attach patches to a ticket in the `ticket tracker`_, using the "attach
95 120
   file" button. Please *don't* put the patch in the ticket description
96 121
   or comment unless it's a single line patch.
@@ -98,21 +123,14 @@ Patch style
98 123
 * Name the patch file with a ``.diff`` extension; this will let the ticket
99 124
   tracker apply correct syntax highlighting, which is quite helpful.
100 125
 
  126
+Regardless of the way you submit your work, follow these steps.
  127
+
  128
+* Make sure your code matches our :doc:`coding-style`.
  129
+
101 130
 * Check the "Has patch" box on the ticket details. This will make it
102 131
   obvious that the ticket includes a patch, and it will add the ticket to
103 132
   the `list of tickets with patches`_.
104 133
 
105  
-* The code required to fix a problem or add a feature is an essential part
106  
-  of a patch, but it is not the only part. A good patch should also
107  
-  include a regression test to validate the behavior that has been fixed
108  
-  and to prevent the problem from arising again. Also, if some tickets are
109  
-  relevant to the code that you've written, mention the ticket numbers in
110  
-  some comments in the test so that one can easily trace back the relevant
111  
-  discussions after your patch gets committed and the tickets get closed.
112  
-
113  
-* If the code associated with a patch adds a new feature, or modifies
114  
-  behavior of an existing feature, the patch should also contain
115  
-  documentation.
116 134
 
117 135
 Non-trivial patches
118 136
 -------------------
4  docs/internals/contributing/writing-code/unit-tests.txt
@@ -36,9 +36,7 @@ with this sample ``settings`` module, ``cd`` into the Django
36 36
     ./runtests.py --settings=test_sqlite
37 37
 
38 38
 If you get an ``ImportError: No module named django.contrib`` error,
39  
-you need to add your install of Django to your ``PYTHONPATH``. For
40  
-more details on how to do this, read
41  
-:ref:`pointing-python-at-the-new-django-version`.
  39
+you need to add your install of Django to your ``PYTHONPATH``.
42 40
 
43 41
 Using another ``settings`` module
44 42
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
222  docs/internals/contributing/writing-code/working-with-git.txt
... ...
@@ -0,0 +1,222 @@
  1
+Working with Git and GitHub
  2
+===========================
  3
+
  4
+Django uses `Git`_ for its source control. You can `download
  5
+<http://git-scm.com/download>`_ Git, but it's often easier to install with
  6
+your operating system's package manager.
  7
+
  8
+Django's `Git repository`_ is hosted on `GitHub`_, and it is recommended
  9
+that you also work using GitHub.
  10
+
  11
+After installing Git the first thing you should do is setup your name and
  12
+email::
  13
+
  14
+  $ git config --global user.name "Firstname Lastname"
  15
+  $ git config --global user.email "your_email@youremail.com"
  16
+
  17
+Note that ``user.name`` should be your real name, not your GitHub nick. GitHub
  18
+should know the email you use in the ``user.email`` field, as this will be
  19
+used to associate your commits with your GitHub account.
  20
+
  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.
  26
+
  27
+.. _Git: http://git-scm.com/
  28
+.. _GitHub: https://github.com/
  29
+.. _Git repository: https://github.com/django/django/
  30
+
  31
+Setting up local repository
  32
+---------------------------
  33
+
  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
+
  37
+    git clone git@github.com:github_nick/django.git
  38
+
  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::
  42
+
  43
+    git remote add upstream git@github.com:django/django.git
  44
+    git fetch upstream
  45
+
  46
+You can add other remotes similarly, for example::
  47
+
  48
+    git remote add akaariai git@github.com:akaariai/django.git
  49
+
  50
+Working on a ticket
  51
+-------------------
  52
+
  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::
  55
+
  56
+    git checkout -b ticket_xxxxx upstream/master
  57
+
  58
+If you are working for a fix on the 1.4 branch, you would instead do::
  59
+
  60
+    git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x
  61
+
  62
+Assume the work is carried on ticket_xxxxx branch. Make some changes and
  63
+commit them::
  64
+
  65
+    git commit
  66
+
  67
+When writing the commit message, you should follow the :ref:`commit message
  68
+guidelines <committing-guidlines>` to ease the work of the committer. If
  69
+you're uncomfortable with English, try at least to describe precisely what the
  70
+commit does.
  71
+
  72
+If you need to do additional work on your branch, commit as often as
  73
+necessary::
  74
+
  75
+    git commit -m 'Added two more tests for edge cases'
  76
+
  77
+Publishing work
  78
+~~~~~~~~~~~~~~~
  79
+
  80
+You can publish your work on GitHub by just using::
  81
+
  82
+  git push origin ticket_xxxxx
  83
+
  84
+When you go to your GitHub page you will notice a new branch has been created.
  85
+If you are working on a Trac ticket, you should mention in the ticket that
  86
+your work is available from branch ticket_xxxxx of your github repo. Include a
  87
+link to your branch.
  88
+
  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.
  96
+
  97
+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:
  99
+
  100
+* Commits with one logical change in each, following the
  101
+  :doc:`coding style <coding-style>`.
  102
+
  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.
  106
+
  107
+* Documentation and tests, if needed. Actually tests are always needed, except
  108
+  for documentation changes.
  109
+
  110
+* The test suite passes and the documentation builds without warnings.
  111
+
  112
+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".
  116
+
  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.
  122
+
  123
+Rebasing branches
  124
+~~~~~~~~~~~~~~~~~
  125
+
  126
+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::
  131
+
  132
+    git rebase -i HEAD~2
  133
+
  134
+The HEAD~2 above is shorthand for two latest commits. The above command
  135
+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.
  140
+
  141
+You can also use the "edit" option in rebase. This way you can change a single
  142
+commit. For example::
  143
+
  144
+    git rebase -i HEAD~3
  145
+    # Choose edit, pick, pick for the commits
  146
+    # Now you are able to rework the commit (use git add normally to add changes)
  147
+    # When finished, commit work with "--amend" and continue
  148
+    git commit --amend
  149
+    # reword the commit message if needed
  150
+    git rebase --continue
  151
+    # The second and third commit should be applied.
  152
+
  153
+If you need to change an already published topic branch at GitHub, you will
  154
+need to force-push the changes::
  155
+
  156
+    git push -f origin ticket_xxxxx
  157
+
  158
+Note that this will rewrite history of ticket_xxxxx - if you check the commit
  159
+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.
  162
+
  163
+After upstream has changed
  164
+~~~~~~~~~~~~~~~~~~~~~~~~~~
  165
+
  166
+When upstream (django/django) has changed, you should rebase your work. To
  167
+do this, use::
  168
+
  169
+  git fetch upstream
  170
+  git rebase
  171
+
  172
+The work is automatically rebased using the branch you forked on, in the
  173
+example case using upstream/master.
  174
+
  175
+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
  178
+rebase --continue``. At any point you can use ``git rebase --abort`` to return
  179
+to the original state.
  180
+
  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.
  186
+
  187
+After review
  188
+------------
  189
+
  190
+It is unusual to get any non-trivial amount of code into core without changes
  191
+requested by reviewers. In this case, it is often a good idea to add the
  192
+changes as one incremental commit to your work. This allows the reviewer to
  193
+easily check what changes you have done::
  194
+
  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
  202
+
  203
+    - Fixed whitespace errors in foo/bar
  204
+    - Reworded the doc string of the_method()
  205
+
  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.
  210
+
  211
+The committer is likely to squash the review commit into the previous commit
  212
+when committing the code.
  213
+
  214
+Summary
  215
+-------
  216
+
  217
+* Work on GitHub if possible.
  218
+* Announce your work on the Trac ticket by linking to your GitHub branch.
  219
+* When you have something ready, make a pull request.
  220
+* Make your pull requests as good as you can.
  221
+* When doing fixes to your work, use ``git rebase -i`` to squash the commits.
  222
+* When upstream has changed, do ``git fetch upstream; git rebase``.
229  docs/internals/git.txt
... ...
@@ -0,0 +1,229 @@
  1
+=================================
  2
+The Django source code repository
  3
+=================================
  4
+
  5
+When deploying a Django application into a real production environment, you
  6
+will almost always want to use `an official packaged release of Django`_.
  7
+However, if you'd like to try out in-development code from an upcoming release
  8
+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.
  11
+
  12
+.. _an official packaged release of Django: https://www.djangoproject.com/download/
  13
+
  14
+High-level overview
  15
+===================
  16
+
  17
+The Django source code repository uses `Git`_ to track changes to the code
  18
+over time, so you'll need a copy of the Git client (a program called ``git``)
  19
+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`_.
  22
+
  23
+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.
  26
+
  27
+The Git repository includes several `branches`_:
  28
+
  29
+* ``master`` contains the main in-development code which will become
  30
+  the next packaged release of Django. This is where most development
  31
+  activity is focused.
  32
+
  33
+* ``stable/A.B.x`` are the maintenance branches. They are used to support
  34
+  older versions of Django.
  35
+
  36
+* ``soc20XX/<project>`` branches were used by students who worked on Django
  37
+  during the 2009 and 2010 Google Summer of Code programs.
  38
+
  39
+* ``attic/<project>`` branches were used to develop major or experimental new
  40
+  features without affecting the rest of Django's code.
  41
+
  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.
  45
+
  46
+The source code for `Djangoproject.com <https://www.djangoproject.com/>`_ Web
  47
+site can be found at `github.com/django/djangoproject.com
  48
+<https://github.com/django/djangoproject.com>`_.
  49
+
  50
+.. _Git: http://git-scm.com/
  51
+.. _documentation: http://git-scm.com/documentation
  52
+.. _branches: https://github.com/django/django/branches
  53
+.. _tags: https://github.com/django/django/tags
  54
+
  55
+Working with Django's master branch
  56
+===================================
  57
+
  58
+If you'd like to try out the in-development code for the next release of
  59
+Django, or if you'd like to contribute to Django by fixing bugs or developing
  60
+new features, you'll want to get the code from the master branch.
  61
+
  62
+Note that this will get *all* of Django: in addition to the top-level
  63
+``django`` module containing Python code, you'll also get a copy of Django's
  64
+documentation, test suite, packaging scripts and other miscellaneous bits.
  65
+Django's code will be present in your clone as a directory named
  66
+``django``.
  67
+
  68
+To try out the in-development code with your own applications, simply place
  69
+the directory containing your clone on your Python import path. Then
  70
+``import`` statements which look for Django will find the ``django`` module
  71
+within your clone.
  72
+
  73
+If you're going to be working on Django's code (say, to fix a bug or
  74
+develop a new feature), you can probably stop reading here and move
  75
+over to :doc:`the documentation for contributing to Django
  76
+</internals/contributing/index>`, which covers things like the preferred
  77
+coding style and how to generate and submit a patch.
  78
+
  79
+Branches
  80
+========
  81
+
  82
+Django uses branches for two main purposes:
  83
+
  84
+1. Development of major or experimental features, to keep them from
  85
+   affecting progress on other work in master.
  86
+
  87
+2. Security and bug-fix support for older releases of Django, during
  88
+   their support lifetimes.
  89
+
  90
+Feature-development branches
  91
+----------------------------
  92
+
  93
+.. admonition:: Historical information
  94
+
  95
+    Since Django moved to Git in 2012, anyone can clone the repository and
  96
+    create his own branches, alleviating the need for official branches in the
  97
+    source code repository.
  98
+
  99
+    The following section is mostly useful if you're exploring the repository's
  100
+    history, for example if you're trying to understand how some features were
  101
+    designed.
  102
+
  103
+Feature-development branches tend by their nature to be temporary. Some
  104
+produce successful features which are merged back into Django's master to
  105
+become part of an official release, but others do not; in either case there
  106
+comes a time when the branch is no longer being actively worked on by any
  107
+developer. At this point the branch is considered closed.
  108
+
  109
+Unfortunately, Django used to be maintained with the Subversion revision
  110
+control system, that has no standard way of indicating this. As a workaround,
  111
+branches of Django which are closed and no longer maintained were moved into
  112
+``attic``.
  113
+
  114
+For reference, the following are branches whose code eventually became
  115
+part of Django itself, and so are no longer separately maintained:
  116
+
  117
+* ``boulder-oracle-sprint``: Added support for Oracle databases to
  118
+  Django's object-relational mapper. This has been part of Django
  119
+  since the 1.0 release.
  120
+
  121
+* ``gis``: Added support for geographic/spatial queries to Django's
  122
+  object-relational mapper. This has been part of Django since the 1.0
  123
+  release, as the bundled application ``django.contrib.gis``.
  124
+
  125
+* ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to
  126
+  Django. This has been part of Django since the 0.90 release.
  127
+
  128
+* ``magic-removal``: A major refactoring of both the internals and
  129
+  public APIs of Django's object-relational mapper. This has been part
  130
+  of Django since the 0.95 release.
  131
+
  132
+* ``multi-auth``: A refactoring of :doc:`Django's bundled
  133
+  authentication framework </topics/auth>` which added support for
  134
+  :ref:`authentication backends <authentication-backends>`. This has
  135
+  been part of Django since the 0.95 release.
  136
+
  137
+* ``new-admin``: A refactoring of :doc:`Django's bundled
  138
+  administrative application </ref/contrib/admin/index>`. This became part of
  139
+  Django as of the 0.91 release, but was superseded by another
  140
+  refactoring (see next listing) prior to the Django 1.0 release.
  141
+
  142
+* ``newforms-admin``: The second refactoring of Django's bundled
  143
+  administrative application. This became part of Django as of the 1.0
  144
+  release, and is the basis of the current incarnation of
  145
+  ``django.contrib.admin``.
  146
+
  147
+* ``queryset-refactor``: A refactoring of the internals of Django's
  148
+  object-relational mapper. This became part of Django as of the 1.0
  149
+  release.
  150
+
  151
+* ``unicode``: A refactoring of Django's internals to consistently use
  152
+  Unicode-based strings in most places within Django and Django
  153
+  applications. This became part of Django as of the 1.0 release.
  154
+
  155
+When Django moved from SVN to Git, the information about branch merges wasn't
  156
+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::
  160
+
  161
+  ac64e91a0cadc57f4bc5cd5d66955832320ca7a1 553a20075e6991e7a60baee51ea68c8adc520d9a 0cb8e31823b2e9f05c4ae868c19f5f38e78a5f2e
  162
+  79e68c225b926302ebb29c808dda8afa49856f5c d0f57e7c7385a112cb9e19d314352fc5ed5b0747 aa239e3e5405933af6a29dac3cf587b59a099927
  163
+  5cf8f684237ab5addaf3549b2347c3adf107c0a7 cb45fd0ae20597306cd1f877efc99d9bd7cbee98 e27211a0deae2f1d402537f0ebb64ad4ccf6a4da
  164
+  f69cf70ed813a8cd7e1f963a14ae39103e8d5265 d5dbeaa9be359a4c794885c2e9f1b5a7e5e51fb8 d2fcbcf9d76d5bb8a661ee73dae976c74183098b
  165
+  aab3a418ac9293bb4abd7670f65d930cb0426d58 4ea7a11659b8a0ab07b0d2e847975f7324664f10 adf4b9311d5d64a2bdd58da50271c121ea22e397
  166
+  ff60c5f9de3e8690d1e86f3e9e3f7248a15397c8 7ef212af149540aa2da577a960d0d87029fd1514 45b4288bb66a3cda401b45901e85b645674c3988
  167
+  9dda4abee1225db7a7b195b84c915fdd141a7260 4fe5c9b7ee09dc25921918a6dbb7605edb374bc9 3a7c14b583621272d4ef53061287b619ce3c290d
  168
+  a19ed8aea395e8e07164ff7d85bd7dff2f24edca dc375fb0f3b7fbae740e8cfcd791b8bccb8a4e66 42ea7a5ce8aece67d16c6610a49560c1493d4653
  169
+  9c52d56f6f8a9cdafb231adf9f4110473099c9b5 c91a30f00fd182faf8ca5c03cd7dbcf8b735b458 4a5c5c78f2ecd4ed8859cd5ac773ff3a01bccf96
  170
+  953badbea5a04159adbfa970f5805c0232b6a401 4c958b15b250866b70ded7d82aa532f1e57f96ae 5664a678b29ab04cad425c15b2792f4519f43928
  171
+  471596fc1afcb9c6258d317c619eaf5fd394e797 4e89105d64bb9e04c409139a41e9c7aac263df4c 3e9035a9625c8a8a5e88361133e87ce455c4fc13
  172
+  9233d0426537615e06b78d28010d17d5a66adf44 6632739e94c6c38b4c5a86cf5c80c48ae50ac49f 18e151bc3f8a85f2766d64262902a9fcad44d937
  173
+
  174
+.. _available as a grafts file: https://github.com/ramiro/django-git-grafts
  175
+
  176
+Additionally, the following branches are closed, but their code was
  177
+never merged into Django and the features they aimed to implement
  178
+were never finished:
  179
+
  180
+* ``full-history``
  181
+
  182
+* ``generic-auth``
  183
+
  184
+* ``multiple-db-support``
  185
+
  186
+* ``per-object-permissions``
  187
+
  188
+* ``schema-evolution``
  189
+
  190
+* ``schema-evolution-ng``
  191
+
  192
+* ``search-api``
  193
+
  194
+* ``sqlalchemy``
  195
+
  196
+All of the above-mentioned branches now reside in ``attic``.
  197
+
  198
+Finally, the repository contains ``soc2009/xxx`` and ``soc2010/xxx`` feature
  199
+branches, used for Google Summer of Code projects.
  200
+
  201
+Support and bugfix branches
  202
+---------------------------
  203
+
  204
+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
+
  211
+These branches can be found in the repository as ``stable/A.B.x``
  212
+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
  214
+``stable/1.0.x`` was created to receive bug fixes, and shortly after the
  215
+release of Django 1.1 the branch ``stable/1.1.x`` was created.
  216
+
  217
+Official support for the above mentioned releases has expired, and so they no
  218
+longer receive direct maintenance from the Django project. However, the
  219
+branches continue to exist and interested community members have occasionally
  220
+used them to provide unofficial support for old Django releases.
  221
+
  222
+Tags
  223
+====
  224
+
  225
+Each Django release is tagged and signed by Django's release manage.
  226
+
  227
+The tags can be found on GitHub's `tags`_ page.
  228
+
  229
+.. _tags: https://github.com/django/django/tags
2  docs/internals/index.txt
@@ -20,4 +20,4 @@ the hood".
20 20
    committers
21 21
    release-process
22 22
    deprecation
23  
-   svn
  23
+   git
2  docs/internals/release-process.txt
@@ -84,6 +84,8 @@ person will be responsible for making sure that bug fixes are applied to both
84 84
 trunk and the maintained micro-release branch. This person will also work with
85 85
 the release manager to decide when to release the micro releases.
86 86
 
  87
+.. _backwards-compatibility-policy:
  88
+
87 89
 Supported versions
88 90
 ==================
89 91
 
254  docs/internals/svn.txt
... ...
@@ -1,254 +0,0 @@
1  
-=================================
2  
-The Django source code repository
3  
-=================================
4  
-
5  
-
6  
-When deploying a Django application into a real production
7  
-environment, you will almost always want to use `an official packaged
8  
-release of Django`_. However, if you'd like to try out in-development
9  
-code from an upcoming release or contribute to the development of
10  
-Django, you'll need to obtain a checkout from Django's source code
11  
-repository. This document covers the way the code repository is laid
12  
-out and how to work with and find things in it.
13  
-
14  
-
15  
-.. _an official packaged release of Django: https://www.djangoproject.com/download/
16  
-
17  
-
18  
-High-level overview
19  
-===================
20  
-
21  
-The Django source code repository uses `Subversion`_ to track changes
22  
-to the code over time, so you'll need a copy of the Subversion client
23  
-(a program called ``svn``) on your computer, and you'll want to
24  
-familiarize yourself with the basics of how Subversion
25  
-works. Subversion's Web site offers downloads for various operating
26  
-systems, and `a free online book`_ is available to help you get up to
27  
-speed with using Subversion.
28  
-
29  
-The Django Subversion repository is located online at
30  
-`code.djangoproject.com/svn <https://code.djangoproject.com/svn/>`_. `A
31  
-friendly Web-based interface for browsing the code`_ is also
32  
-available, though when using Subversion you'll always want to use the
33  
-repository address instead. At the top level of the repository are two
34  
-directories: ``django`` contains the full source code for all Django