src/doc/en/developer: move "git the hard way" earlier, present "git-trac" only as an additional convenience

Author: Matthias Koeppe

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

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

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: