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.

1 files changed, 39 insertions, 21 deletions

diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt
index 1e28dc4491..5bd7774cb3 100644
--- a/docs/internals/contributing/writing-code/submitting-patches.txt
+++ b/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
 with associated patches will get fixed *far* more quickly than those
 without patches.
 
+Typo fixes and trivial documentation changes
+--------------------------------------------
+
+If you are fixing a really trivial issue, for example changing a word in the
+documentation, the preferred way to provide the patch is using GitHub pull
+requests without a Trac ticket. Trac tickets are still acceptable.
+
+See the :doc:`working-with-git` for more details on how to use pull requests.
+
 "Claiming" tickets
 ------------------
 
@@ -69,28 +78,44 @@ Of course, going through the steps of claiming tickets is overkill in some
 cases. In the case of small changes, such as typos in the documentation or
 small bugs that will only take a few minutes to fix, you don't need to jump
 through the hoops of claiming tickets. Just submit your patch and be done with
-it.
+it. Of course, it is always acceptable, regardless of the ticket's ownership
+status, to submit patches to a ticket if you happen to have a patch ready.
 
 .. _patch-style:
 
 Patch style
 -----------
 
-* Make sure your code matches our :doc:`coding-style`.
+Make sure that any contribution you do fulfills at least the following
+requirements:
+
+* The code required to fix a problem or add a feature is an essential part
+  of a patch, but it is not the only part. A good patch should also
+  include a regression test to validate the behavior that has been fixed
+  and to prevent the problem from arising again. Also, if some tickets are
+  relevant to the code that you've written, mention the ticket numbers in
+  some comments in the test so that one can easily trace back the relevant
+  discussions after your patch gets committed and the tickets get closed.
+
+* If the code associated with a patch adds a new feature, or modifies
+  behavior of an existing feature, the patch should also contain
+  documentation.
+
+You can use either GitHub branches and pull requests or direct patches
+to publish your work. If you use the Git workflow, then you should
+announce your branch in the ticket by including a link to your branch.
+When you think your work is ready to be merged in create a pull request.
+See the :doc:`working-with-git` documentation for mode details.
 
-* Submit patches in the format returned by the ``svn diff`` command.
+You can also use patches in Trac. When using this style, follow these
+guidelines.
+
+* Submit patches in the format returned by the ``git diff`` command.
   An exception is for code changes that are described more clearly in
   plain English than in code. Indentation is the most common example; it's
   hard to read patches when the only difference in code is that it's
   indented.
 
-  Patches in ``git diff`` format are also acceptable.
-
-* When creating patches, always run ``svn diff`` from the top-level
-  ``trunk`` directory -- i.e. the one that contains ``django``, ``docs``,
-  ``tests``, ``AUTHORS``, etc. This makes it easy for other people to
-  apply your patches.
-
 * Attach patches to a ticket in the `ticket tracker`_, using the "attach
   file" button. Please *don't* put the patch in the ticket description
   or comment unless it's a single line patch.
@@ -98,21 +123,14 @@ Patch style
 * Name the patch file with a ``.diff`` extension; this will let the ticket
   tracker apply correct syntax highlighting, which is quite helpful.
 
+Regardless of the way you submit your work, follow these steps.
+
+* Make sure your code matches our :doc:`coding-style`.
+
 * Check the "Has patch" box on the ticket details. This will make it
   obvious that the ticket includes a patch, and it will add the ticket to
   the `list of tickets with patches`_.
 
-* The code required to fix a problem or add a feature is an essential part
-  of a patch, but it is not the only part. A good patch should also
-  include a regression test to validate the behavior that has been fixed
-  and to prevent the problem from arising again. Also, if some tickets are
-  relevant to the code that you've written, mention the ticket numbers in
-  some comments in the test so that one can easily trace back the relevant
-  discussions after your patch gets committed and the tickets get closed.
-
-* If the code associated with a patch adds a new feature, or modifies
-  behavior of an existing feature, the patch should also contain
-  documentation.
 
 Non-trivial patches
 -------------------