From b183abfc8d09ecc1ee4ace4e0c6d11bd9d42b2fb Mon Sep 17 00:00:00 2001 From: Subhrajyoti Sen Date: Fri, 27 Jan 2017 17:04:07 +0530 Subject: [PATCH] [1.11.x] Fixed #26708 -- Updated the contributing tutorial to use a GitHub workflow. Backport of f5bf11c72b267d717dd4379ec80f9f7c5185f80f from master --- docs/intro/contributing.txt | 108 +++++++++++++++++++++++------------- 1 file changed, 68 insertions(+), 40 deletions(-) diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt index 75414410f2..e5160d82f8 100644 --- a/docs/intro/contributing.txt +++ b/docs/intro/contributing.txt @@ -59,7 +59,7 @@ tools and the processes involved. Specifically, we'll be covering the following: * Writing a test for your patch. * Writing the code for your patch. * Testing your patch. -* Generating a patch file for your changes. +* Submitting a pull request. * Where to look for more information. Once you're done with the tutorial, you can look through the rest of @@ -308,6 +308,19 @@ __ http://djangoci.com :ref:`run the tests using a different database `. +Creating a branch for your patch +================================ + +Before making any changes, create a new branch for the ticket: + +.. code-block:: console + + $ git checkout -b ticket_24788 + +You can choose any name that you want for the branch, "ticket_24788" is an +example. All changes made in this branch will be specific to the ticket and +won't affect the main copy of the code that we cloned earlier. + Writing some tests for your ticket ================================== @@ -497,31 +510,18 @@ the ``versionadded`` bit is all about, see an explanation of how to build a copy of the documentation locally, so you can preview the HTML that will be generated. -Generating a patch for your changes -=================================== +Previewing your changes +======================= -Now it's time to generate a patch file that can be uploaded to Trac or applied -to another copy of Django. To get a look at the content of your patch, run the -following command: +Now it's time to go through all the changes made in our patch. To display the +differences between your current copy of Django (with your changes) and the +revision that you initially checked out earlier in the tutorial: .. code-block:: console $ git diff -This will display the differences between your current copy of Django (with -your changes) and the revision that you initially checked out earlier in the -tutorial. - -Once you're done looking at the patch, hit the ``q`` key to exit back to the -command line. If the patch's content looked okay, you can run the following -command to save the patch file to your current working directory: - -.. code-block:: console - - $ git diff > 24788.diff - -You should now have a file in the root Django directory called ``24788.diff``. -This patch file contains all your changes and should look this: +Use the arrow keys to move up and down. .. code-block:: diff @@ -603,23 +603,52 @@ This patch file contains all your changes and should look this: # NullBooleanField is a bit of a special case because its presentation (widget) # is different than its data. This is handled transparently, though. -So what do I do next? -===================== +When you're done previewing the patch, hit the ``q`` key to return to the +command line. If the patch's content looked okay, it's time to commit the +changes. -Congratulations, you've generated your very first Django patch! Now that you've -got that under your belt, you can put those skills to good use by helping to -improve Django's codebase. Generating patches and attaching them to Trac -tickets is useful, however, since we are using git - adopting a more :doc:`git -oriented workflow ` is -recommended. +Committing the changes in the patch +=================================== -Since we never committed our changes locally, perform the following to get your -git branch back to a good starting point: +To commit the changes: .. code-block:: console - $ git reset --hard HEAD - $ git checkout master + $ git commit -a + +This opens up a text editor to type the commit message. Follow the :ref:`commit +message guidelines ` and write a message like: + +.. code-block:: text + + Fixed #24788 -- Allowed Forms to specify a prefix at the class level. + +Pushing the commit and making a pull request +============================================ + +After committing the patch, send it to your fork on GitHub (substitute +"ticket_24788" with the name of your branch if it's different): + +.. code-block:: console + + $ git push origin ticket_24788 + +You can create a pull request by visiting the `Django GitHub page +`_. You'll see your branch under "Your +recently pushed branches". Click "Compare & pull request" next to it. + +On the next page that displays a preview of the patch, you would click +"Create pull request". + +Next steps +========== + +Congratulations, you've learned how to make a pull request to Django! Details +of more advanced techniques you may need are in +:doc:`/internals/contributing/writing-code/working-with-git`. + +Now you can put those skills to good use by helping to improve Django's +codebase. More information for new contributors ------------------------------------- @@ -665,13 +694,12 @@ __ https://code.djangoproject.com/query?status=new&status=reopened&has_patch=0&e __ https://code.djangoproject.com/query?status=new&status=reopened&needs_better_patch=1&easy=1&col=id&col=summary&col=status&col=owner&col=type&col=milestone&order=priority __ https://code.djangoproject.com/query?status=new&status=reopened&needs_tests=1&easy=1&col=id&col=summary&col=status&col=owner&col=type&col=milestone&order=priority -What's next? ------------- +What's next after creating a pull request? +------------------------------------------ After a ticket has a patch, it needs to be reviewed by a second set of eyes. -After uploading a patch or submitting a pull request, be sure to update the -ticket metadata by setting the flags on the ticket to say "has patch", -"doesn't need tests", etc, so others can find it for review. Contributing -doesn't necessarily always mean writing a patch from scratch. Reviewing -existing patches is also a very helpful contribution. See -:doc:`/internals/contributing/triaging-tickets` for details. +After submitting a pull request, update the ticket metadata by setting the +flags on the ticket to say "has patch", "doesn't need tests", etc, so others +can find it for review. Contributing doesn't necessarily always mean writing a +patch from scratch. Reviewing existing patches is also a very helpful +contribution. See :doc:`/internals/contributing/triaging-tickets` for details.