From 532ca2e08961b6ffd925c28581c45795986755ee Mon Sep 17 00:00:00 2001
From: David Lord <davidism@gmail.com>
Date: Tue, 23 May 2017 11:18:48 -0700
Subject: [PATCH] reorganize git instructions

---
 CONTRIBUTING.rst | 58 ++++++++++++++++++++++++++++--------------------
 1 file changed, 34 insertions(+), 24 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 80b6af35..22828608 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -24,32 +24,42 @@ Reporting issues
 Submitting patches
 ==================
 
-
-- `Make sure you have a github account <https://github.com/join>`_
-- `Download and install latest version of git on your
-  machine <https://git-scm.com/downloads>`_
-- `Set up your username in git 
-  <https://help.github.com/articles/setting-your-username-in-git/>`_
-- `Set up your email in git 
-  <https://help.github.com/articles/setting-your-email-in-git/>`_
-- Fork flask to your github account (Click the Fork button)
-- `Copy your github fork locally 
-  <https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork>`_
-- Create a branch to identify the issue you would like to work 
-  on (eg 2287-dry-test-suite)
-- Using your favorite editor, make your changes, 
-  `committing as you go <http://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes>`_
-- Include tests if your patch is supposed to solve a bug, and explain
-  clearly under which circumstances the bug happens. Make sure the test fails
-  without your patch.
-- Try to follow `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_, but you
-  may ignore the line-length-limit if following it would make the code uglier.
-- `Run tests. 
-  <https://github.com/pallets/flask/blob/master/CONTRIBUTING.rst#running-the-testsuite>`_
-  When tests pass push changes to github and `create pull request 
-  <https://help.github.com/articles/creating-a-pull-request/>`_
+First time setup
+----------------
+
+- Download and install the `latest version of git`_.
+- Configure git with your `username`_ and `email`_.
+- Make sure you have a `GitHub account`_.
+- Fork Flask to your GitHub account by clicking the `Fork`_ button.
+- `Clone`_ your GitHub fork locally.
+- Add the main repository as a remote to update later.
+  ``git remote add pallets https://github.com/pallets/flask``
+
+.. _GitHub account: https://github.com/join
+.. _latest version of git: https://git-scm.com/downloads
+.. _username: https://help.github.com/articles/setting-your-username-in-git/
+.. _email: https://help.github.com/articles/setting-your-email-in-git/
+.. _Fork: https://github.com/pallets/flask/pull/2305#fork-destination-box
+.. _Clone: https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork
+
+Start coding
+------------
+
+- Create a branch to identify the issue you would like to work on (e.g.
+  ``2287-dry-test-suite``)
+- Using your favorite editor, make your changes, `committing as you go`_.
+- Try to follow `PEP8`_, but you may ignore the line length limit if following
+  it would make the code uglier.
+- Include tests that cover any code changes you make. Make sure the test fails
+  without your patch. `Run the tests. <contributing-testsuite_>`_.
+- Push your commits to GitHub and `create a pull request`_.
 - Celebrate 🎉
 
+.. _committing as you go: http://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes
+.. _PEP8: https://pep8.org/
+.. _create a pull request: https://help.github.com/articles/creating-a-pull-request/
+
+.. _contributing-testsuite:
 
 Running the testsuite
 ---------------------