DOC: Simplify and update git setup page (gh-16671)

* DOC: Simplify and update git setup page

Changed title from "Getting started with Git development"
to more specific "Setting up git for NumPy development"

Updated the outdated GitHub screenshot for forking button, added
more screenshots.

Simplified the narrative.

Fixed bad github links (always pointed to NumPy's github).

Clarified SSH setup, role, and effect on git remote -v.

Clarified meaning of "upstream" and "origin".

Replaced read of .git/config (platform-specific) with call to git config.

* DOC: Add links, remove section from PR #16671

Per suggestion, removed outdated advice on getting pull branches.

Added back rST anchors, should have left them in.

* DOC: Add page anchor for PR #16671

Add '.. _development-setup:' page anchor.

1 files changed, 132 insertions, 99 deletions

diff --git a/doc/source/dev/gitwash/development_setup.rst b/doc/source/dev/gitwash/development_setup.rst
index 9027dda64..a7e9c28b9 100644
--- a/doc/source/dev/gitwash/development_setup.rst
+++ b/doc/source/dev/gitwash/development_setup.rst
@@ -1,145 +1,178 @@
-====================================
-Getting started with Git development
-====================================
+.. _development-setup:
 
-This section and the next describe in detail how to set up git for working
-with the NumPy source code.  If you have git already set up, skip to
-:ref:`development-workflow`.
+##############################################################################
+Setting up git for NumPy development
+##############################################################################
 
-Basic Git setup
-###############
+To contribute code or documentation, you first need
 
-* :ref:`install-git`.
-* Introduce yourself to Git::
+#. git installed on your machine
+#. a GitHub account
+#. a fork of NumPy
 
-      git config --global user.email you@yourdomain.example.com
-      git config --global user.name "Your Name Comes Here"
 
-.. _forking:
+******************************************************************************
+Install git
+******************************************************************************
+
+You may already have git; check by typing ``git --version``. If it's
+installed you'll see some variation of ``git version 2.11.0``.
+If instead you see ``command is not recognized``, ``command not
+found``, etc.,
+`install git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_.
 
-Making your own copy (fork) of NumPy
-####################################
+Then set your name and email: ::
 
-You need to do this only once.  The instructions here are very similar
-to the instructions at http://help.github.com/forking/ - please see that
-page for more detail.  We're repeating some of it here just to give the
-specifics for the NumPy_ project, and to suggest some default names.
+  git config --global user.email you@yourdomain.example.com
+  git config --global user.name "Your Name"
 
 .. _set-up-and-configure-a-github-account:
 
-Set up and configure a github_ account
-======================================
+******************************************************************************
+Create a GitHub account
+******************************************************************************
 
-If you don't have a github_ account, go to the github_ page, and make one.
+If you don't have a GitHub account, visit https://github.com/join to create
+one.
 
-You then need to configure your account to allow write access - see the
-``Generating SSH keys`` help on `github help`_.
+.. _forking:
 
-Create your own forked copy of NumPy_
-=========================================
+******************************************************************************
+Create a NumPy fork
+******************************************************************************
 
-#. Log into your github_ account.
-#. Go to the NumPy_ github home at `NumPy github`_.
-#. Click on the *fork* button:
+``Forking`` has two steps -- visit GitHub to create a fork repo in your
+account, then make a copy of it on your own machine.
 
-   .. image:: forking_button.png
+Create the fork repo
+==============================================================================
 
-   After a short pause, you should find yourself at the home page for
-   your own forked copy of NumPy_.
+#. Log into your GitHub account.
+#. Go to the `NumPy GitHub home <https://github.com/numpy/numpy>`_.
+#. At the upper right of the page, click ``Fork``:
 
-.. include:: git_links.inc
+   .. image:: forking_button.png
 
+   You'll see
 
-.. _set-up-fork:
+   .. image:: forking_message.png
 
-Set up your fork
-################
+   and then you'll be taken to the home page of your forked copy:
 
-First you follow the instructions for :ref:`forking`.
+   .. image:: forked_page.png
 
-Overview
-========
 
-::
+.. _set-up-fork:
 
-   git clone https://github.com/your-user-name/numpy.git
-   cd numpy
-   git remote add upstream https://github.com/numpy/numpy.git
+Make the local copy
+==============================================================================
 
-In detail
-=========
+#. In the directory where you want the copy created, run ::
 
-Clone your fork
----------------
+    git clone https://github.com/your-user-name/numpy.git
 
-#. Clone your fork to the local computer with ``git clone
-   https://github.com/your-user-name/numpy.git``
-#. Investigate.  Change directory to your new repo: ``cd numpy``. Then
-   ``git branch -a`` to show you all branches.  You'll get something
-   like::
+   You'll see something like: ::
 
-      * master
-      remotes/origin/master
+    $ git clone https://github.com/your-user-name/numpy.git
+    Cloning into 'numpy'...
+    remote: Enumerating objects: 12, done.
+    remote: Counting objects: 100% (12/12), done.
+    remote: Compressing objects: 100% (12/12), done.
+    remote: Total 175837 (delta 0), reused 0 (delta 0), pack-reused 175825
+    Receiving objects: 100% (175837/175837), 78.16 MiB | 9.87 MiB/s, done.
+    Resolving deltas: 100% (139317/139317), done.
 
-   This tells you that you are currently on the ``master`` branch, and
-   that you also have a ``remote`` connection to ``origin/master``.
-   What remote repository is ``remote/origin``? Try ``git remote -v`` to
-   see the URLs for the remote.  They will point to your github_ fork.
+   A directory ``numpy`` is created on your machine. (If you already have
+   a numpy directory, GitHub will choose a different name like ``numpy-1``.)
+   ::
 
-   Now you want to connect to the upstream `NumPy github`_ repository, so
-   you can merge in changes from trunk.
+    $ ls -l
+    total 0
+    drwxrwxrwx 1 bjn bjn 4096 Jun 20 07:20 numpy
 
 .. _linking-to-upstream:
 
-Linking your repository to the upstream repo
---------------------------------------------
+#. Give the name ``upstream`` to the main NumPy repo: ::
+
+    cd numpy
+    git remote add upstream https://github.com/numpy/numpy.git
+
+#. Set up your repository so ``git pull`` pulls from ``upstream`` by
+   default: ::
+
+    git config branch.master.remote upstream
+    git config branch.master.merge refs/heads/master
 
-::
+******************************************************************************
+Look it over
+******************************************************************************
 
-   cd numpy
-   git remote add upstream https://github.com/numpy/numpy.git
+#. The branches shown by ``git branch -a`` will include
 
-``upstream`` here is just the arbitrary name we're using to refer to the
-main NumPy_ repository at `NumPy github`_.
+   - the ``master`` branch you just cloned on your own machine
+   - the ``master`` branch from your fork on GitHub, which git named
+     ``origin`` by default
+   - the ``master`` branch on the the main NumPy repo, which you named
+     ``upstream``.
 
-Just for your own satisfaction, show yourself that you now have a new
-'remote', with ``git remote -v show``, giving you something like::
+   ::
 
-   upstream	https://github.com/numpy/numpy.git (fetch)
-   upstream	https://github.com/numpy/numpy.git (push)
-   origin	https://github.com/your-user-name/numpy.git (fetch)
-   origin	https://github.com/your-user-name/numpy.git (push)
+     master
+     remotes/origin/master
+     remotes/upstream/master
 
-To keep in sync with changes in NumPy, you want to set up your repository
-so it pulls from ``upstream`` by default.  This can be done with::
+   If ``upstream`` isn't there, it will be added after you access the
+   NumPy repo with a command like ``git fetch`` or ``git pull``.
 
-   git config branch.master.remote upstream
-   git config branch.master.merge refs/heads/master
 
-You may also want to have easy access to all pull requests sent to the
-NumPy repository::
+#. The repos shown by ``git remote -v show`` will include your fork on GitHub
+   and the main repo: ::
 
-   git config --add remote.upstream.fetch '+refs/pull/*/head:refs/remotes/upstream/pr/*'
+    upstream	https://github.com/numpy/numpy.git (fetch)
+    upstream	https://github.com/numpy/numpy.git (push)
+    origin	https://github.com/your-user-name/numpy.git (fetch)
+    origin	https://github.com/your-user-name/numpy.git (push)
 
-Your config file should now look something like (from
-``$ cat .git/config``)::
+#. ``git config --list`` will include ::
 
-   [core]
-           repositoryformatversion = 0
-           filemode = true
-           bare = false
-           logallrefupdates = true
-           ignorecase = true
-           precomposeunicode = false
-   [remote "origin"]
-           url = https://github.com/your-user-name/numpy.git
-           fetch = +refs/heads/*:refs/remotes/origin/*
-   [remote "upstream"]
-           url = https://github.com/numpy/numpy.git
-           fetch = +refs/heads/*:refs/remotes/upstream/*
-           fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*
-   [branch "master"]
-           remote = upstream
-           merge = refs/heads/master
+    user.email=your_email@example.com
+    user.name=Your Name
+    remote.origin.url=git@github.com:your-github-id/numpy.git
+    remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
+    branch.master.remote=upstream
+    branch.master.merge=refs/heads/master
+    remote.upstream.url=https://github.com/numpy/numpy.git
+    remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/*
 
 .. include:: git_links.inc
+
+
+******************************************************************************
+Optional: set up SSH keys to avoid passwords
+******************************************************************************
+
+Cloning your NumPy fork repo required no password, because it read the remote
+repo without changing it. Later, though, submitting your pull requests will
+write to it, and GitHub will ask for your username and password -- even though
+it's your own repo. You can eliminate this authentication without compromising
+security by `setting up SSH keys \
+<https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh>`_.
+
+**If you set up the keys before cloning**, the instructions above change
+slightly. Instead of ::
+
+  git clone https://github.com/your-user-name/numpy.git
+
+run ::
+
+  git clone git@github.com:numpy/numpy.git
+
+and instead of showing an ``https`` URL,  ``git remote -v`` will show ::
+
+  origin  git@github.com:your-user-name/numpy.git (fetch)
+  origin  git@github.com:your-user-name/numpy.git (push)
+
+
+**If you have cloned already** and want to start using SSH, see
+`Switching remote URLs from HTTPS to SSH \
+<https://help.github.com/en/github/using-git/changing-a-remotes-url#switching-remote-urls-from-https-to-ssh>`_.