Trac #33648: Update/reorder git instructions in Developer's Guide

(from #33088)

In the developer guide, move "git the hard way" earlier and present
"git-trac" only as an additional convenience.
Also note that the first configuration using sagetrac-mirror is not
recommended for users who use VS Code
(https://trac.sagemath.org/ticket/33589#comment:13)

URL: https://trac.sagemath.org/33648
Reported by: mkoeppe
Ticket author(s): Matthias Koeppe
Reviewer(s): Dima Pasechnik

src/doc/en/developer/advanced_git.rst

@@ -10,8 +10,7 @@ This chapter covers some advanced uses of git that go beyond what is
 required to work with branches. These features can be used in Sage
 development, but are not really necessary to contribute to Sage. If
 you are just getting started with Sage development, you should read
-:ref:`chapter-walkthrough` instead. If you are new to git, please see
-:ref:`chapter-manual-git`.
+:ref:`chapter-walkthrough` and :ref:`chapter-manual-git` instead.
 
 
 Detached Heads and Reviewing Tickets
@@ -171,7 +170,8 @@ successfully, it would be possible to merge in our branch
 ``some_code`` into develop. This would produce the same source files
 and avoid unnecessary recompilations. However, it makes reading git's
 history very unpleasant: For example, it is hard to keep track of changes etc.,
-as one cannot simply pursue the first parent of each git commit.
+as one cannot simply pursue the first parent of each git commit
+(``git log --first-parent``).
 
 
 .. _section-git-recovery:

src/doc/en/developer/git_background.rst

@@ -7,8 +7,7 @@ Tips and References
 ===================
 
 This chapter contains additional material about the git revision
-control system. It is not necessary if you stick with the Sage
-development scripts. See :ref:`chapter-git-setup` for the minimal
+control system.  See :ref:`chapter-git-setup` for the minimal
 steps needed for Sage development.
 
 

src/doc/en/developer/git_trac.rst

@@ -2,42 +2,21 @@
 
 .. _chapter-git_trac:
 
-=======================================
-Collaborative Development with Git-Trac
-=======================================
-
-Sometimes you will only want to work on local changes to Sage, for
-your own private needs.  However, typically it is beneficial to
-share code and ideas with others; the manner in which the
-`Sage project <https://www.sagemath.org>`_ does this (as well as fixing
-bugs and upgrading components) is in a very collaborative and
-public setting on `the Sage Trac server <https://trac.sagemath.org>`_
-(the Sage bug and enhancement tracker).
-
-One can use ``git`` :ref:`the hard way <chapter-manual-git>` for this,
-but this section explains how to use the helper ``git trac`` command, which
-simplifies many of the most common actions in collaboration on Sage. Some
-of the :ref:`tutorials <section-git-tutorials>` we suggest may be helpful
-in navigating what they are for.
-
-Most of the commands in the following section will not work unless
-you have an account on Trac. If you want to contribute to Sage, it
-is a good idea to get an account now (see :ref:`section-trac-account`).
+====================================
+Optional: Using the Git-Trac Command
+====================================
 
+Git is a separate project from trac, and the two do not know how to
+talk to each other. To simplify the development, we have a special
+``git trac`` subcommand for the git suite. Note that this really is
+only to simplify interaction with our trac issue management, you can
+perform every development task with just git and a web browser.
 
 .. _section-git_trac-install:
 
 Installing the Git-Trac Command
 ===============================
 
-Git is a separate project from trac, and the two do not know how to
-talk to each other. To simplify the development, we have a special
-``git trac`` subcommand for the git suite. Note that this really is
-only to simplify interaction with our trac issue management, you can
-perform every development task with just git and a web browser. See
-:ref:`chapter-manual-git` instead if you prefer to do everything by
-hand::
-
     [user@localhost]$ git clone https://github.com/sagemath/git-trac-command.git
     Cloning into 'git-trac-command'...
     [...]
@@ -149,10 +128,6 @@ secured with SSH keys, which you must have set up as in
 :ref:`section-trac-ssh-key`. Read-only access happens through the
 fetch url and does not require SSH.
 
-Finally, if you do not want to use the ``git trac`` subcommand at all
-then you can set up the remote by hand as described in the section on
-:ref:`section-git-trac`.
-
 
 Trac Tickets and Git Branches
 =============================

src/doc/en/developer/index.rst

@@ -59,13 +59,12 @@ development!
   need to learn about revision control; we use the software Git for this
   purpose.
 
-  - :ref:`Here is <chapter-walkthrough>` an overview of our development flow.
-  - :ref:`Unfamiliar with Git or revision control? <chapter-git_trac>`
   - :ref:`How to install it? <section-git-install>`
   - :ref:`How to configure it for use with Trac? <section-git-setup-name>`
+  - :ref:`Here is <chapter-walkthrough>` an overview of our development flow.
 
-Git for Sage development
-========================
+Git and Trac for Sage development
+=================================
 
 First Steps with Git
 --------------------
@@ -78,41 +77,24 @@ Sage uses git for version control.
    git_setup
    walk_through
 
-The git-trac command
---------------------
-
-Putting your local changes on a Trac ticket.
-
-.. toctree::
-   :maxdepth: 2
-
-   git_trac
-
 .. _section-git-tricks-and-tips:
 
-Git Tricks & Tips
------------------
+Using Git with Trac
+-------------------
 
-When ``git trac`` is not enough.
+To contribute back your changes to Sage source code to the project,
+you will need a ticket on the
+`Sage trac server <http://trac.sagemath.org>`_.
 
 .. toctree::
    :maxdepth: 2
 
+   trac
    manual_git
    git_background
    advanced_git
    workflows
-
-Sage Trac and tickets
-=====================
-
-All changes to Sage source code require a ticket on the
-`Sage trac server <http://trac.sagemath.org>`_.
-
-.. toctree::
-   :maxdepth: 2
-
-   trac
+   git_trac
 
 
 .. _section-writing-code-for-sage:

src/doc/en/developer/manual_git.rst

@@ -2,19 +2,11 @@
 
 .. _chapter-manual-git:
 
-================
-Git the Hard Way
-================
+===================================
+Using Git with the Sage Trac Server
+===================================
 
-If you have no ``git`` experience, we recommend you to read the
-:ref:`chapter-git_trac` chapter instead. The ``git-trac`` simplifies the
-interaction with our git and trac servers.
-
-If you want to contribute using ``git`` only, you are at the right place. This
-chapter will tell you how to do so, assuming some basic familiarity with ``git``. In
-particular, you should have read :ref:`chapter-walkthrough` first.
-
-Randall Munroe has provided a `basic overview <http://xkcd.com/1597/>`_.
+Now we continue our introduction to git from :ref:`chapter-walkthrough`.
 
 In the following, we assume that you are in the source directory of Sage (``SAGE_ROOT``),
 obtained either from a source tarball or by cloning a Sage git repository
@@ -42,16 +34,19 @@ repository, use these commands::
 
     [user@localhost sage]$ git remote add trac https://github.com/sagemath/sagetrac-mirror.git -t master
     [user@localhost sage]$ git remote set-url --push trac git@trac.sagemath.org:sage.git
+
+Instead of ``trac`` you can use any other name you want, of course.
+To verify that it is set up correctly::
+
     [user@localhost sage]$ git remote -v
     origin      https://github.com/sagemath/sage.git (fetch)
     origin      https://github.com/sagemath/sage.git (push)
     trac        https://github.com/sagemath/sagetrac-mirror.git (fetch)
     trac        git@trac.sagemath.org:sage.git (push)
 
-Instead of ``trac`` you can use any local name you want, of course. It
-is perfectly fine to have multiple remote repositories for git, think
-of them as bookmarks. You can then use ``git pull`` to get changes and
-``git push`` to upload your local changes using::
+It is perfectly fine to have multiple remote repositories for git,
+think of them as bookmarks. You can then use ``git pull`` to get
+changes and ``git push`` to upload your local changes using::
 
     [user@localhost sage]$ git <push|pull> trac [ARGS]
 
@@ -65,19 +60,20 @@ of them as bookmarks. You can then use ``git pull`` to get changes and
     tell git which branch you want to get from trac. See the
     :ref:`section-git-checkout` section for examples.
 
-We set up the remote here to perform read-only operations (``fetch``)
-using HTTPS from a mirror of the trac repository and write
-operations (``push``) using the ssh protocol (specified by the ``git@``
-part).
-
-Note that to use the ssh protocol, you
-need to have a trac account and to set up your ssh public key as
-described in `Trac authentication through ssh
+Note that write operations (``push``) use the ssh protocol (specified by the ``git@``
+part). For this to work, you need to have a trac account and to set up your ssh public
+key as described in `Trac authentication through ssh
 <http://doc.sagemath.org/html/en/developer/trac.html#trac-authentication-through-ssh>`_.
 Authentication is necessary if you want to upload anything to ensure
 that it really is from you.
 
-If you want to use ssh only, use the following commands instead::
+The above instructions set up the remote to perform read-only operations (``fetch``)
+using HTTPS from a mirror of the trac repository instead. The mirror is faster and
+more reliable than our git server. However, this configuration is not recommended if
+you use VS Code as an IDE.
+
+If you want to use ssh only for both ``fetch`` and ``push``, use the
+following commands instead::
 
     [user@localhost sage]$ git remote add trac git@trac.sagemath.org:sage.git -t master
     [user@localhost sage]$ git remote -v

src/doc/en/developer/trac.rst

@@ -6,9 +6,15 @@
 The Sage Trac Server
 ====================
 
-All changes to Sage source code have to go through the `Sage Trac
-development server <https://trac.sagemath.org>`_. The purpose
-of the Sage trac server is to
+Sometimes you will only want to work on local changes to Sage, for
+your own private needs.  However, typically it is beneficial to
+share code and ideas with others; the manner in which the
+`Sage project <https://www.sagemath.org>`_ does this (as well as fixing
+bugs and upgrading components) is in a very collaborative and
+public setting on `the Sage Trac server <https://trac.sagemath.org>`_
+(the Sage bug and enhancement tracker).
+
+The purpose of the Sage trac server is to
 
 1. Provide a place for discussion on issues and store a permanent
    record.
@@ -413,7 +419,7 @@ Only the Sage release manager will close tickets. Most likely, this is
 not you nor will your trac account have the necessary permissions. If
 you feel strongly that a ticket should be closed or deleted, then
 change the status of the ticket to *needs review* and change the
-milestone to *sage-duplictate/invalid/wontfix*. You should also
+milestone to *sage-duplicate/invalid/wontfix*. You should also
 comment on the ticket, explaining why it should be closed. If another
 developer agrees, he sets the ticket to *positive review*.
 

src/doc/en/developer/walk_through.rst

@@ -10,17 +10,25 @@ This section is a concise overview of the Sage development process. In
 it, we will see how to make changes to the Sage source code and record
 them in the ``git`` revision control system.
 
-In the following section on :ref:`chapter-git_trac` we will look at
-communicating these changes back to the Sage project.  We also have a handy
-`one-page "cheat sheet"
+We also have a handy `one-page "cheat sheet"
 <http://github.com/sagemath/git-trac-command/raw/master/doc/git-cheat-sheet.pdf>`_
 of commonly used git commands that you can print out and leave on your
 desk.  We have some :ref:`recommended references and tutorials
 <section-git-tutorials>` as well.
 
-You can alternatively fork and create a merge request at
-`GitLab <https://gitlab.com/sagemath/sage>`_ which will automatically fetch
-your code and open a ticket on our trac server.
+In the following sections on :ref:`chapter-sage-trac` and
+:ref:`section-git-tricks-and-tips` we will look at communicating these
+changes back to the Sage project.  All changes to Sage source code
+have to go through the `Sage Trac development server
+<https://trac.sagemath.org>`_.
+
+As an alternative to using the Trac server directly, you can fork and
+create a Merge Request (MR) at `GitLab <https://gitlab.com/sagemath/sage>`_
+which will automatically fetch your code and open a ticket on our trac
+server.
+
+Pull Requests (PR) on GitHub are currently not supported by the
+SageMath project.
 
 
 .. _section-walkthrough-setup-git: