Reorganize git commands (#263)

* Move the minimal configuration instructions.

* Move the remote configuration instructions.

* Move the pushing changes and synching remotes sections.

* First cleanup pass.

* Remove the "Maintaining a repository" section.

* Move the "Reverting a Merged Pull Request" section under "Working with Git".

* Fix incorrect markup.

Author: ezio-melotti

committing.rst

@@ -268,23 +268,6 @@ understands the justification for the change).  Also, if a non-core developer
 contributed to the resolution, it is good practice to credit them.
 
 
-Reverting a Commit
-------------------
-
-To revert a merged pull request, press the ``Revert`` button at the bottom of
-the pull request.  It will bring up the page to create a new pull request where
-the commit can be reverted.  It also creates a new branch on the main CPython
-repository.  Delete the branch once the pull request has been merged.
-
-Always include the reason for reverting the commit to help others understand
-why it was done.  The reason should be included as part of the commit message,
-for example::
-
-   Revert bpo-NNNN: Fix Spam Module (GH-111)
-
-   Reverts python/cpython#111.
-   Reason: This commit broke the buildbot.
-
 
 Working with Git_
 =================
@@ -313,107 +296,6 @@ into a state you aren't happy with.
 .. _Git: https://git-scm.com/
 
 
-Minimal Configuration
----------------------
-
-If you use Git as a committer of patches (your own or others), you should
-set up some basic options.  Here are the minimal options you need to activate:
-
-* Your *name* and *email*: these settings defines what will be used when you
-  commit changes::
-
-   git config --global user.name "Your Name"
-   git config --global user.email [email protected]
-
-``--global`` flag sets configuration options at a global level, if instead you
-want to set it at a project level use ``--local``, instead.
-
-* *Under Windows*, you should also enable the *autocrlf* option, which will
-  fix any Windows-specific line endings your text editor might insert when you
-  create or modify versioned files.  The public repository has a hook which
-  will reject all changesets having the wrong line endings, so enabling this
-  extension on your local computer is in your best interest.
-  ::
-
-     git config --global core.autocrlf input
-
-
-Remotes Setup
--------------
-
-
-.. _remote-configuration:
-
-Configuration
-'''''''''''''
-
-There are several possible ways how to set up your git repository. This section
-discusses the simplest approach of having a single directory with two remotes,
-one pointing to private fork, the other one being the official repository.
-
-Assuming you have :ref:`cloned the official repository <checkout>` here is how
-your current setup should look like::
-
-   $ git remote -v    # show remotes
-   origin  https://github.com/python/cpython (fetch)
-   origin  https://github.com/python/cpython (push)
-
-You can have multiple remotes defined for a single repository, the usual approach
-is to have ``origin`` pointing to your :ref:`private fork <forking>`, and ``upstream``
-pointing to the official repository. To do so, here are the steps needed to have
-that setup::
-
-   git remote set-url origin https://github.com/<your-username>/cpython
-   git remote add upstream https://github.com/python/cpython
-
-After that, your remotes configuration should look like this::
-
-   $ git remote -v    # show remotes
-   origin  https://github.com/<your-username>/cpython (fetch)
-   origin  https://github.com/<your-username>/cpython (push)
-   upstream  https://github.com/python/cpython (fetch)
-   upstream  https://github.com/python/cpython (push)
-
-At any point in time you can use SSH-based URL instead of HTTPS-based ones.
-
-
-.. _committing-push-changes:
-
-Pushing changes
-'''''''''''''''
-
-You have two remotes configured (see previous section for setup). Publishing
-your changes to any of them is as simple as specifying the name of the remote
-upon your push. Assuming I am working on a local branch ``bug1234`` and I want to
-push it to my private fork I do::
-
-   git push origin bug1234
-
-Option ``-u|--set-upstream`` creates a remote-tracking branch that tracks what
-have been pushed to ``origin``::
-
-   git push -u origin bug1234
-
-That allows to avoid rebasing beyond already pushed commits.
-``git status --branch`` and ``git branch --verbose`` remind that the branch(es)
-have not pushed commits.
-
-
-Synchronizing remotes
-'''''''''''''''''''''
-
-To synchronize your fork, from the official repository you need to execute following
-commands::
-
-   git fetch upstream         # fetch remote changes
-   git checkout master        # checkout your current master branch
-   git merge upstream/master  # merge remote changes into your local master branch
-   git push origin master     # publish changes to your private fork
-
-The above steps can be executed against any branch you wish to, just replace master
-with an appropriate branch name.
-
-
 .. _committing-active-branches:
 
 Active branches
@@ -454,34 +336,19 @@ Developers can apply labels to GitHub pull requests).
 .. _cherry_picker.py: https://github.com/python/core-workflow/tree/master/cherry_picker
 
 
-.. _forking:
-
-Forking repository
-------------------
-
-Forking a repository on GitHub is as simple as clicking Fork button in the right
-upper corner at https://github.com/python/cpython.
-
+Reverting a Merged Pull Request
+-------------------------------
 
-Maintaining a repository
-------------------------
+To revert a merged pull request, press the ``Revert`` button at the bottom of
+the pull request.  It will bring up the page to create a new pull request where
+the commit can be reverted.  It also creates a new branch on the main CPython
+repository.  Delete the branch once the pull request has been merged.
 
-The Git object database and other files/directories under ``.git`` require
-periodic maintenance and cleanup. For example, commit editing leaves
-unreferenced objects (dangling objects, in git terminology) and these
-objects should be pruned to avoid collecting cruft in the DB. The
-command ``git gc`` is used for maintenance. Git automatically runs
-``git gc --auto`` as a part of some commands to do quick maintenance.
-Users are recommended to run ``git gc --aggressive`` from time to
-time; ``git help gc`` recommends to run it  every few hundred
-changesets; for CPython it should be something like once a week
-(GitHub itself runs the command weekly, so new checkouts do not need to
-perform this step).
+Always include the reason for reverting the commit to help others understand
+why it was done.  The reason should be included as part of the commit message,
+for example::
 
-``git gc --aggressive`` not only removes dangling objects, it also
-repacks object database into indexed and better optimized pack(s); it
-also packs symbolic references (branches and tags).
+   Revert bpo-NNNN: Fix Spam Module (GH-111)
 
-From time to time run ``git fsck --strict`` to verify integrity of
-the database. ``git fsck`` may produce a list of dangling objects;
-that's not an error, just a reminder to perform regular maintenance.
+   Reverts python/cpython#111.
+   Reason: This commit broke the buildbot.

gitbootcamp.rst

@@ -10,6 +10,7 @@ relevant to CPython's workflow.
 
 .. contents::
 
+.. _fork-cpython:
 
 Forking CPython GitHub Repository
 ---------------------------------
@@ -24,24 +25,61 @@ You'll only need to do this once.
 
 4. Your fork will be created at https://github.com/<username>/cpython.
 
+.. _clone-your-fork:
 
 Cloning The Forked CPython Repository
 -------------------------------------
 
 You'll only need to do this once.  From your command line::
 
    $ git clone [email protected]:<username>/cpython.git
+
+It is also recommended to configure an ``upstream`` remote::
+
    $ cd cpython
    $ git remote add upstream [email protected]:python/cpython.git
 
+You can also use SSH-based or HTTPS-based URLs.
 
 Listing the Remote Repositories
 -------------------------------
 
-To list the remote repositories that are configured, along with their urls::
+To list the remote repositories that are configured, along with their URLs::
 
    $ git remote -v
 
+You should have two remotes: ``origin`` pointing to your fork,
+and ``upstream`` pointing to the official CPython repository::
+
+   origin  [email protected]:<your-username>/devguide.git (fetch)
+   origin  [email protected]:<your-username>/devguide.git (push)
+   upstream        [email protected]:python/devguide.git (fetch)
+   upstream        [email protected]:python/devguide.git (push)
+
+
+.. _set-up-name-email:
+
+Setting Up Your Name and Email Address
+--------------------------------------
+::
+
+   $ git config --global user.name "Your Name"
+   $ git config --global user.email [email protected]
+
+The ``--global`` flag sets these globally,
+``--local`` sets them only for the current project.
+
+.. _autocrlf:
+
+Enabling ``autocrlf`` on Windows
+--------------------------------
+
+The *autocrlf* option will fix automatically any Windows-specific line endings.
+This should be enabled on Windows, since the public repository has a hook which
+will reject all changesets having the wrong line endings.
+::
+
+    $ git config --global core.autocrlf input
 
 Creating and Switching Branches
 -------------------------------
@@ -139,6 +177,21 @@ To re-apply the last stashed change::
 
    $ git stash pop
 
+.. _commit-changes:
+
+Committing Changes
+------------------
+
+Add the files you want to commit::
+
+   $ git add <filename>
+
+Commit the files::
+
+   $ git commit -m '<message>'
+
+
+.. _push-changes:
 
 Pushing Changes
 ---------------

pullrequest.rst

@@ -107,21 +107,22 @@ Here is a quick overview of how you can contribute to CPython on GitHub:
 
 #. :ref:`Get started <setup>` and set up your system
 
-#. Fork `CPython`_ on GitHub (using the Fork button in the upper-right on GitHub)
+#. :ref:`Fork CPython <fork-cpython>` (using the Fork button in the
+   upper-right on GitHub)
+
+#. :ref:`Clone your GitHub fork and add an "upstream" remote <clone-your-fork>`
 
 #. :ref:`Build Python <compiling>` on your system
 
 #. :ref:`Run tests <runtests>` after you have built Python
 
-#. :ref:`Add an "upstream" Remote in Git <remote-configuration>` (using SSH,
-   or you can `use HTTPS`_)
-
 #. :ref:`Create a Branch in Git <pullrequest-steps>` where you can work on
    changes
 
 #. :ref:`Run tests <runtests>` again
 
-#. :ref:`Push commits <committing-push-changes>` to your GitHub repo
+#. :ref:`Commit <commit-changes>` and :ref:`push <push-changes>`
+   changes to your GitHub fork
 
 #. `Create Pull Request`_ on GitHub to merge a branch from your fork
 

setup.rst

@@ -34,36 +34,27 @@ installation directions. You may also want to consider a graphical client
 such as `TortoiseGit <https://tortoisegit.org/>`_ or
 `GitHub Desktop <https://desktop.github.com/>`_.
 
-You may also wish to
-`set up an SSH key <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>`_
+You may also wish to set up :ref:`your name and email <set-up-name-email>`
+and `an SSH key
+<https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>`_
 as this will allow you to interact with GitHub without typing a username
 and password each time you execute a command, such as ``git pull``,
-``git push``, or ``git fetch``.
-
+``git push``, or ``git fetch``.  On Windows, you should also
+:ref:`enable autocrlf <autocrlf>`.
 
 .. _checkout:
 
 Getting the Source Code
 -----------------------
 
-One should always work from a working copy of the CPython source code.
-While it may
-be tempting to work from the copy of Python you already have installed on your
-machine, it is very likely that you will be working from out-of-date code as
-the Python core developers are constantly updating and fixing things in their
-:abbr:`VCS (version control system)`. It also means you will have better tool
-support through the VCS as it will provide a diff tool, etc.
-
-To get a working copy of the :ref:`in-development <indevbranch>` branch of
-CPython, run::
-
-    git clone https://github.com/python/cpython
+In order to get a copy of the source code you should first :ref:`fork the
+Python repository on GitHub <fork-cpython>` and then :ref:`create a local
+clone of your private fork and configure the remotes <clone-your-fork>`.
 
 If you want a working copy of an already-released version of Python,
 i.e., a version in :ref:`maintenance mode <maintbranch>`, you can checkout
-a release branch. For instance, to checkout a working copy of Python 3.5, do::
-
-   git checkout 3.5
+a release branch. For instance, to checkout a working copy of Python 3.5,
+do ``git checkout 3.5``.
 
 You will need to re-compile CPython when you do such an update.