Ticket #10190: trac-10190_mercurial.patch

File trac-10190_mercurial.patch, 13.3 KB (added by mvngu, 12 years ago)
  • doc/en/developer/walk_through.rst

    # HG changeset patch
    # User Minh Van Nguyen <nguyenminh2@gmail.com>
    # Date 1288513006 25200
    # Node ID d758a5f9270247a4639a2bef4e3a802859041483
    # Parent  120c07be6358d93bcff503363d379c26b8342f2b
    #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.
    * Provide a template ~/.hgrc configuration file.
    
    diff --git a/doc/en/developer/walk_through.rst b/doc/en/developer/walk_through.rst
    a b  
    9191subdirectory. Running Sage, or rebuilding, will use this version of
    9292the source.
    9393
     94.. warning::
     95
     96    In some cases, the cloning process can take dozens of minutes or
     97    longer. This might be due to your hardware, your system load, and
     98    other unforeseen factors. The main focus of this chapter is to
     99    introduce new contributors to the Sage development
     100    process. Cloning or creating a sandbox is a simple way for new
     101    contributors to safely experiment with their local Sage
     102    installation. Mercurial offers a more powerful feature,
     103    i.e. Mercurial queues, for efficiently and safely working with the
     104    Sage library in your local Sage installation, without having to
     105    create a clone of that library. On a first reading of this
     106    chapter, you do not need to know anything about Mercurial
     107    queues. However, be aware that Mercurial queues fits "naturally"
     108    into the process of creating a patch, updating a patch, and patch
     109    management in general.
     110
    94111Now you can safely experiment with Sage code as much as you would
    95112like. A cloned version of the Sage library can be found under
    96113
     
    204221:ref:`section-review-patches-queues-walkthrough` for another way to apply
    205222patches with Mercurial.
    206223
     224.. note::
     225
     226    Sage offers a basic interface to the Mercurial revision control
     227    system. At the Sage command prompt, you can access some features
     228    of Mercurial through commands having the ``hg_sage.`` prefix. For
     229    a full listing of all available interfaces to Mercurial, type
     230    ``hg_sage.`` at the Sage command prompt and press the tab key
     231    ``Tab`` or ``tab``.
     232
     233    You can directly use the version of Mercurial that is distributed
     234    with Sage. Most, if not all, Sage developers do not use Sage's
     235    interface to Mercurial as this interface is very basic. You will
     236    find that directly using Mercurial (whether that be the version
     237    installed by your package manager or the version shipped with
     238    Sage), instead of through Sage's interface, can allow you to be
     239    much more productive.
     240
    207241To actually test out a patch, do the following.  Even if you're new to Sage
    208242development and tentative about reviewing, reporting the success or failure
    209243of these steps on the ticket Trac page will be quite helpful:
     
    259293as follows:
    260294
    261295#. Make a fresh clone, as discussed in :ref:`section-create-sandbox`.
    262 #. Apply any precursor patches not in your current version, as
     296
     297.. warning::
     298
     299    In some cases, the cloning process can take dozens of minutes or
     300    longer. This might be due to your hardware, your system load, and
     301    other unforeseen factors. The main focus of this chapter is to
     302    introduce new contributors to the Sage development
     303    process. Cloning or creating a sandbox is a simple way for new
     304    contributors to safely experiment with their local Sage
     305    installation. Mercurial offers a more powerful feature,
     306    i.e. Mercurial queues, for efficiently and safely working with the
     307    Sage library in your local Sage installation, without having to
     308    create a clone of that library. On a first reading of this
     309    chapter, you do not need to know anything about Mercurial
     310    queues. However, be aware that Mercurial queues fits "naturally"
     311    into the process of creating a patch, updating a patch, and patch
     312    management in general.
     313
     3142. Apply any precursor patches not in your current version, as
    263315   demonstrated in :ref:`section-review-patch-walkthrough`.
    264316#. Edit source files (see :ref:`section-modify-source` for location),
    265317   test building Sage, test functionality, and so on.
     
    298350   the ticket number.
    299351#. Create a ``.hgrc``  Mercurial configuration file in your home
    300352   directory.  Specify your name and email address here, so it will
    301    identify you as the author of a patch, in the form `` Bill Smith
    302    <bsmith@bigu.edu>``. Here is a template for your ``.hgrc`` file:
    303 
    304    ::
     353   identify you as the author of a patch, in the form ``Bill Smith
     354   <bsmith@bigu.edu>``. Here is a template for your ``.hgrc`` file::
    305355
    306356       [ui]
     357       editor = /usr/bin/vim
    307358       username = Carl Friedrich Gauss <cfgauss@uni-goettingen.de>
    308359
    309360       [extensions]
    310        # Enable the Mercurial queue extension.
     361       # Enable the Mercurial queues extension.
    311362       hgext.mq =
     363       # Enable the record, qrecord and crecord extensions for cherry picking.
     364       hgext.record =
     365
     366       [diff]
     367       # Format diff output using Git style.
     368       git = True
     369       # Prevent qrefresh from updating timestamps. If you're keeping your patch
     370       # queue under revision control, it can be quite annoying when every qrefresh
     371       # updates the timestamps in your patch. The following prevents this from
     372       # happening.
     373       nodates = 1
    312374
    313375   The Mercurial project website ``http://mercurial.selenic.com``
    314376   contains many tutorials on using Mercurial.
     
    326388   package your changes as a single Mercurial "changeset", allowing
    327389   others (reviewers, release manager) to add your changes to their
    328390   versions of Sage.  An editor window will pop up (set your favorite
    329    editor in the ``.hgrc`` file mentioned above) where you should
    330    enter a *one-line* message describing the patch. This message is
    331    known as the commit message for your patch.  You are encouraged to
    332    write commit messages of the form
    333    ``Trac XXXX: <description-goes-here>`` using the Trac ticket number
    334    and then have a concise description, e.g. "fix echelon form error"
    335    or "add echelon form over finite fields." Some people also write
    336    commit messages in the form ``#xxxx: <description-goes-here>``,
    337    which is also acceptable. A key information to provide in a commit
    338    message is the ticket number.
    339 #. Run the command ``hg_sage.log()`` from the Sage command line.  The
     391   editor in the ``.hgrc`` file mentioned above or refer to note
     392   below) where you should enter at least a *one-line* summary message
     393   describing the patch. This message is known as the commit message
     394   for your patch.  A commit message provides a high-level description
     395   of a patch. Think of a commit message as a log entry. The commit
     396   message of a patch can be structured as a one-liner::
     397
     398       #xxxx: <your summary log entry here>
     399
     400   where ``#xxxx`` is the number of the corresponding ticket. It is
     401   very important that you include the corresponding ticket number in
     402   your commit message. The ticket number can help track down bugs and
     403   provide relevant background information. A commit message can also
     404   span multiple lines::
     405
     406       #xxxx: <summary log entry>
     407       Ticket #xxxx implements the following awesome features:
     408
     409       - Get Sage to solve the Riemann hypothesis.
     410       - Solve the Collatz conjecture.
     411
     412   A commit message that spans multiple lines should allow you to
     413   provide much more explanation of your patch. However, note that by
     414   default Mercurial shows the first line of a commit message together
     415   with some brief information. For example, here is log entry that is
     416   output in brief by default using the command ``hg log``::
     417
     418       changeset:   15055:f761e275e31e
     419       tag:         tip
     420       user:        Minh Van Nguyen <nguyenminh2@gmail.com>
     421       date:        Sun Oct 31 01:16:46 2010 -0700
     422       summary:     #10190: warnings and notes about commit message, cloning, and setting the text editor
     423
     424   The full log is obtained using the command ``hg log -v``, where the
     425   switch ``-v`` means "verbose". The verbose (or full) log of the
     426   above changeset is::
     427
     428       changeset:   15055:f761e275e31e
     429       tag:         tip
     430       user:        Minh Van Nguyen <nguyenminh2@gmail.com>
     431       date:        Sun Oct 31 01:16:46 2010 -0700
     432       files:       doc/en/developer/walk_through.rst
     433       description:
     434       #10190: warnings and notes about commit message, cloning, and setting the text editor
     435
     436       * Warnings about the inefficiency of cloning and point out that
     437         Mercurial queues fits naturally into the patch management problem.
     438       * Some typo fixes.
     439       * Explain that you can write a commit message that spans multiple lines.
     440       * Instructions on writing/editing a commit message with Vi(m) and then
     441         quit the Vi(m) editor.
     442       * Explain that Sage's interface to Mercurial is very basic and that
     443         directly using Mercurial can allow you to be much more productive.
     444
     445.. note::
     446
     447    By default, Mercurial launches the text editor Vi or Vim
     448    whenever you edit a commit message. You can configure Mercurial to
     449    use your favorite editor by setting the environment variable
     450    ``HGEDITOR`` in your ``~/.bashrc`` file::
     451
     452        HGEDITOR=/path/to/your/favorite/editor; export HGEDITOR
     453
     454    You should replace ``/path/to/your/favorite/editor`` with the
     455    absolute path to your favorite editor. For example, if you want
     456    Mercurial to launch Emacs whenever you want to edit a commit
     457    message, you could set ``HGEDITOR`` as follows in your
     458    ``~/.bashrc``::
     459
     460        HGEDITOR=/usr/bin/emacs; export HGEDITOR
     461
     462    The above configuration assumes that the absolute path of Emacs is
     463    ``/usr/bin/emacs``. You need to find out the exact absolute path of
     464    your favorite editor. If you set ``HGEDITOR`` in your
     465    ``~/.bashrc`` file, it might not take effect until you quit your
     466    terminal and open your terminal again. Another way is to log out
     467    and then log in again.
     468
     469    Another way to configure the editor to be used by Mercurial is via
     470    the Mercurial configuration file ``.hgrc``. If your ``.hgrc`` file
     471    contains a section header called ``[ui]``, you need to add the
     472    line ``editor = /path/to/favorite/editor`` underneath that
     473    header. For example::
     474
     475        [ui]
     476        editor = /usr/bin/emacs
     477        username = Carl Friedrich Gauss <cfgauss@uni-goettingen.de>
     478
     479    In case your ``.hgrc`` file does not contain the header ``[ui]``,
     480    you simply create that header. Note that if you set the editor
     481    both via the environment variable ``HGEDITOR`` and via the line
     482    ``editor = /path/to/favorite/editor``, then Mercurial will search
     483    for an editor in the following order.
     484
     485    #. The ``HGEDITOR`` environment variable.
     486    #. The ``editor`` configuration option in the ``[ui]`` section.
     487    #. The ``VISUAL`` environment variable.
     488    #. The ``EDITOR`` environment variable.
     489    #. Fall back on ``vi`` or ``vim`` if no default editor is set.
     490
     491    If Mercurial launches the Vi or Vim text editor when you edit your
     492    commit message, to begin editing press the key ``I`` to tell Vi(m)
     493    that you want to start inserting text. Then start writing/editing
     494    your commit message. When you are done, press the escape key
     495    ``esc`` or ``Esc``, and enter the characters ``:wq``. These
     496    characters tell Vi(m) to save your commit message and then exit
     497    Vi(m).
     498
     4997. Run the command ``hg_sage.log()`` from the Sage command line.  The
    340500   first entry should be your changeset.  Note the changeset number,
    341501   which is probably 5 decimal digits.
    342502#. Next, issue the command
     
    367527#. Make a new fresh clone.  Read :ref:`section-create-sandbox` to be
    368528   sure you clone the right stuff (i.e. do not clone the branch you
    369529   changed).  We will call this clone ``test2`` here.
    370 #. Apply your patch, but not with ``hg_sage.apply()``.  You want to
     530
     531.. warning::
     532
     533    In some cases, the cloning process can take dozens of minutes or
     534    longer. This might be due to your hardware, your system load, and
     535    other unforeseen factors. The main focus of this chapter is to
     536    introduce new contributors to the Sage development
     537    process. Cloning or creating a sandbox is a simple way for new
     538    contributors to safely experiment with their local Sage
     539    installation. Mercurial offers a more powerful feature,
     540    i.e. Mercurial queues, for efficiently and safely working with the
     541    Sage library in your local Sage installation, without having to
     542    create a clone of that library. On a first reading of this
     543    chapter, you do not need to know anything about Mercurial
     544    queues. However, be aware that Mercurial queues fits "naturally"
     545    into the process of creating a patch, updating a patch, and patch
     546    management in general.
     547
     5482. Apply your patch, but not with ``hg_sage.apply()``.  You want to
    371549   make the changes without doing a commit.  (There is a switch that
    372550   will prevent a commit, but by doing this, you will see how to do
    373551   this at the system level.)  First make