Ticket #10190: trac-10190_mercurial.patch

doc/en/developer/walk_through.rst

@@ -91 +91 @@
 subdirectory. Running Sage, or rebuilding, will use this version of
 the source.
 
+.. warning::
+
+    In some cases, the cloning process can take dozens of minutes or
+    longer. This might be due to your hardware, your system load, and
+    other unforeseen factors. The main focus of this chapter is to
+    introduce new contributors to the Sage development
+    process. Cloning or creating a sandbox is a simple way for new
+    contributors to safely experiment with their local Sage
+    installation. Mercurial offers a more powerful feature,
+    i.e. Mercurial queues, for efficiently and safely working with the
+    Sage library in your local Sage installation, without having to
+    create a clone of that library. On a first reading of this
+    chapter, you do not need to know anything about Mercurial
+    queues. However, be aware that Mercurial queues fits "naturally"
+    into the process of creating a patch, updating a patch, and patch
+    management in general.
+
 Now you can safely experiment with Sage code as much as you would
 like. A cloned version of the Sage library can be found under
 
@@ -204 +221 @@
 :ref:`section-review-patches-queues-walkthrough` for another way to apply
 patches with Mercurial.
 
+.. note::
+
+    Sage offers a basic interface to the Mercurial revision control
+    system. At the Sage command prompt, you can access some features
+    of Mercurial through commands having the ``hg_sage.`` prefix. For
+    a full listing of all available interfaces to Mercurial, type
+    ``hg_sage.`` at the Sage command prompt and press the tab key
+    ``Tab`` or ``tab``.
+
+    You can directly use the version of Mercurial that is distributed
+    with Sage. Most, if not all, Sage developers do not use Sage's
+    interface to Mercurial as this interface is very basic. You will
+    find that directly using Mercurial (whether that be the version
+    installed by your package manager or the version shipped with
+    Sage), instead of through Sage's interface, can allow you to be
+    much more productive.
+
 To actually test out a patch, do the following.  Even if you're new to Sage
 development and tentative about reviewing, reporting the success or failure
 of these steps on the ticket Trac page will be quite helpful:
@@ -259 +293 @@
 as follows:
 
 #. Make a fresh clone, as discussed in :ref:`section-create-sandbox`.
-#. Apply any precursor patches not in your current version, as
+
+.. warning::
+
+    In some cases, the cloning process can take dozens of minutes or
+    longer. This might be due to your hardware, your system load, and
+    other unforeseen factors. The main focus of this chapter is to
+    introduce new contributors to the Sage development
+    process. Cloning or creating a sandbox is a simple way for new
+    contributors to safely experiment with their local Sage
+    installation. Mercurial offers a more powerful feature,
+    i.e. Mercurial queues, for efficiently and safely working with the
+    Sage library in your local Sage installation, without having to
+    create a clone of that library. On a first reading of this
+    chapter, you do not need to know anything about Mercurial
+    queues. However, be aware that Mercurial queues fits "naturally"
+    into the process of creating a patch, updating a patch, and patch
+    management in general.
+
+2. Apply any precursor patches not in your current version, as
    demonstrated in :ref:`section-review-patch-walkthrough`.
 #. Edit source files (see :ref:`section-modify-source` for location),
    test building Sage, test functionality, and so on.
@@ -298 +350 @@
    the ticket number.
 #. Create a ``.hgrc``  Mercurial configuration file in your home
    directory.  Specify your name and email address here, so it will
-   identify you as the author of a patch, in the form `` Bill Smith
-   <bsmith@bigu.edu>``. Here is a template for your ``.hgrc`` file:
-
-   ::
+   identify you as the author of a patch, in the form ``Bill Smith
+   <bsmith@bigu.edu>``. Here is a template for your ``.hgrc`` file::
 
        [ui]
+       editor = /usr/bin/vim
        username = Carl Friedrich Gauss <cfgauss@uni-goettingen.de>
 
        [extensions]
-       # Enable the Mercurial queue extension.
+       # Enable the Mercurial queues extension.
        hgext.mq =
+       # Enable the record, qrecord and crecord extensions for cherry picking.
+       hgext.record =
+
+       [diff]
+       # Format diff output using Git style.
+       git = True
+       # Prevent qrefresh from updating timestamps. If you're keeping your patch
+       # queue under revision control, it can be quite annoying when every qrefresh
+       # updates the timestamps in your patch. The following prevents this from
+       # happening.
+       nodates = 1
 
    The Mercurial project website ``http://mercurial.selenic.com``
    contains many tutorials on using Mercurial.
@@ -326 +388 @@
    package your changes as a single Mercurial "changeset", allowing
    others (reviewers, release manager) to add your changes to their
    versions of Sage.  An editor window will pop up (set your favorite
-   editor in the ``.hgrc`` file mentioned above) where you should
-   enter a *one-line* message describing the patch. This message is
-   known as the commit message for your patch.  You are encouraged to
-   write commit messages of the form
-   ``Trac XXXX: <description-goes-here>`` using the Trac ticket number
-   and then have a concise description, e.g. "fix echelon form error"
-   or "add echelon form over finite fields." Some people also write
-   commit messages in the form ``#xxxx: <description-goes-here>``,
-   which is also acceptable. A key information to provide in a commit
-   message is the ticket number.
-#. Run the command ``hg_sage.log()`` from the Sage command line.  The
+   editor in the ``.hgrc`` file mentioned above or refer to note
+   below) where you should enter at least a *one-line* summary message
+   describing the patch. This message is known as the commit message
+   for your patch.  A commit message provides a high-level description
+   of a patch. Think of a commit message as a log entry. The commit
+   message of a patch can be structured as a one-liner::
+
+       #xxxx: <your summary log entry here>
+
+   where ``#xxxx`` is the number of the corresponding ticket. It is
+   very important that you include the corresponding ticket number in
+   your commit message. The ticket number can help track down bugs and
+   provide relevant background information. A commit message can also
+   span multiple lines::
+
+       #xxxx: <summary log entry>
+       Ticket #xxxx implements the following awesome features:
+
+       - Get Sage to solve the Riemann hypothesis.
+       - Solve the Collatz conjecture.
+
+   A commit message that spans multiple lines should allow you to
+   provide much more explanation of your patch. However, note that by
+   default Mercurial shows the first line of a commit message together
+   with some brief information. For example, here is log entry that is
+   output in brief by default using the command ``hg log``::
+
+       changeset:   15055:f761e275e31e
+       tag:         tip
+       user:        Minh Van Nguyen <nguyenminh2@gmail.com>
+       date:        Sun Oct 31 01:16:46 2010 -0700
+       summary:     #10190: warnings and notes about commit message, cloning, and setting the text editor
+
+   The full log is obtained using the command ``hg log -v``, where the
+   switch ``-v`` means "verbose". The verbose (or full) log of the
+   above changeset is::
+
+       changeset:   15055:f761e275e31e
+       tag:         tip
+       user:        Minh Van Nguyen <nguyenminh2@gmail.com>
+       date:        Sun Oct 31 01:16:46 2010 -0700
+       files:       doc/en/developer/walk_through.rst
+       description:
+       #10190: warnings and notes about commit message, cloning, and setting the text editor
+
+       * Warnings about the inefficiency of cloning and point out that
+         Mercurial queues fits naturally into the patch management problem.
+       * Some typo fixes.
+       * Explain that you can write a commit message that spans multiple lines.
+       * Instructions on writing/editing a commit message with Vi(m) and then
+         quit the Vi(m) editor.
+       * Explain that Sage's interface to Mercurial is very basic and that
+         directly using Mercurial can allow you to be much more productive.
+
+.. note::
+
+    By default, Mercurial launches the text editor Vi or Vim
+    whenever you edit a commit message. You can configure Mercurial to
+    use your favorite editor by setting the environment variable
+    ``HGEDITOR`` in your ``~/.bashrc`` file::
+
+        HGEDITOR=/path/to/your/favorite/editor; export HGEDITOR
+
+    You should replace ``/path/to/your/favorite/editor`` with the
+    absolute path to your favorite editor. For example, if you want
+    Mercurial to launch Emacs whenever you want to edit a commit
+    message, you could set ``HGEDITOR`` as follows in your
+    ``~/.bashrc``::
+
+        HGEDITOR=/usr/bin/emacs; export HGEDITOR
+
+    The above configuration assumes that the absolute path of Emacs is
+    ``/usr/bin/emacs``. You need to find out the exact absolute path of
+    your favorite editor. If you set ``HGEDITOR`` in your
+    ``~/.bashrc`` file, it might not take effect until you quit your
+    terminal and open your terminal again. Another way is to log out
+    and then log in again.
+
+    Another way to configure the editor to be used by Mercurial is via
+    the Mercurial configuration file ``.hgrc``. If your ``.hgrc`` file
+    contains a section header called ``[ui]``, you need to add the
+    line ``editor = /path/to/favorite/editor`` underneath that
+    header. For example::
+
+        [ui]
+        editor = /usr/bin/emacs
+        username = Carl Friedrich Gauss <cfgauss@uni-goettingen.de>
+
+    In case your ``.hgrc`` file does not contain the header ``[ui]``,
+    you simply create that header. Note that if you set the editor
+    both via the environment variable ``HGEDITOR`` and via the line
+    ``editor = /path/to/favorite/editor``, then Mercurial will search
+    for an editor in the following order.
+
+    #. The ``HGEDITOR`` environment variable.
+    #. The ``editor`` configuration option in the ``[ui]`` section.
+    #. The ``VISUAL`` environment variable.
+    #. The ``EDITOR`` environment variable.
+    #. Fall back on ``vi`` or ``vim`` if no default editor is set.
+
+    If Mercurial launches the Vi or Vim text editor when you edit your
+    commit message, to begin editing press the key ``I`` to tell Vi(m)
+    that you want to start inserting text. Then start writing/editing
+    your commit message. When you are done, press the escape key
+    ``esc`` or ``Esc``, and enter the characters ``:wq``. These
+    characters tell Vi(m) to save your commit message and then exit
+    Vi(m).
+
+7. Run the command ``hg_sage.log()`` from the Sage command line.  The
    first entry should be your changeset.  Note the changeset number,
    which is probably 5 decimal digits.
 #. Next, issue the command
@@ -367 +527 @@
 #. Make a new fresh clone.  Read :ref:`section-create-sandbox` to be
    sure you clone the right stuff (i.e. do not clone the branch you
    changed).  We will call this clone ``test2`` here.
-#. Apply your patch, but not with ``hg_sage.apply()``.  You want to
+
+.. warning::
+
+    In some cases, the cloning process can take dozens of minutes or
+    longer. This might be due to your hardware, your system load, and
+    other unforeseen factors. The main focus of this chapter is to
+    introduce new contributors to the Sage development
+    process. Cloning or creating a sandbox is a simple way for new
+    contributors to safely experiment with their local Sage
+    installation. Mercurial offers a more powerful feature,
+    i.e. Mercurial queues, for efficiently and safely working with the
+    Sage library in your local Sage installation, without having to
+    create a clone of that library. On a first reading of this
+    chapter, you do not need to know anything about Mercurial
+    queues. However, be aware that Mercurial queues fits "naturally"
+    into the process of creating a patch, updating a patch, and patch
+    management in general.
+
+2. Apply your patch, but not with ``hg_sage.apply()``.  You want to
    make the changes without doing a commit.  (There is a switch that
    will prevent a commit, but by doing this, you will see how to do
    this at the system level.)  First make