GNU Octave: Basics of Generating a Changeset

Next: General Guidelines, Previous: Building the Development Sources, Up: Contributing Guidelines [Contents][Index]

### D.3 Basics of Generating a Changeset

The best way to contribute is to create a Mercurial changeset and submit it to the bug or patch trackers13. Mercurial is the source code management system currently used to develop Octave. Other forms of contributions (e.g., simple diff patches) are also acceptable, but they slow down the review process. If you want to make more contributions, you should really get familiar with Mercurial. A good place to start is http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial. There you will also find help about how to install Mercurial.

A simple contribution sequence could look like this:

    hg clone http://www.octave.org/hg/octave
                                 # make a local copy of the octave
                                 # source repository
    cd octave
    # change some sources…
    hg commit -m "make Octave the coolest software ever"
                                 # commit the changeset into your
                                 # local repository
    hg export -o ../cool.diff tip
                                 # export the changeset to a diff
                                 # file
    # attach ../cool.diff to your bug report

You may want to get familiar with Mercurial queues to manage your changesets. To work with queues you must activate the extension mq with the following entry in Mercurial’s configuration file `.hgrc` (or `Mercurial.ini` on Windows):

    [extensions]
    mq=

Here is a slightly more complex example using Mercurial queues, where work on two unrelated changesets is done in parallel and one of the changesets is updated after discussion on the bug tracker:

    hg qnew nasty_bug            # create a new patch
    # change sources…
    hg qref                      # save the changes into the patch
    # change even more…
    hg qref -m "solution to nasty bug!"
                                 # save again with commit message
    hg export -o ../nasty.diff tip
                                 # export the patch
    # attach ../nasty.diff to your bug report
    hg qpop                      # undo the application of the patch
                                 # and remove the changes from the
                                 # source tree
    hg qnew doc_improvements     # create an unrelated patch
    # change doc sources…
    hg qref -m "could not find myfav.m in the doc"
                                 # save the changes into the patch
    hg export -o ../doc.diff tip
                                 # export the second patch
    # attach ../doc.diff to your bug report
    hg qpop
    # discussion in the bug tracker …
    hg qpush nasty_bug           # apply the patch again
    # change sources yet again …
    hg qref
    hg export -o ../nasty2.diff tip
    # attach ../nasty2.diff to your bug report

Mercurial has a few more useful extensions that really should be enabled. They are not enabled by default due to a number of factors (mostly because they don’t work in all terminal types).

The following entries in the `.hgrc` are recommended

    [extensions]
    graphlog=
    color=
    progress=
    pager=

For the color extension, default color and formatting of `hg status` can be modified by

    [color]
    status.modified = magenta bold
    status.added = green bold
    status.removed = red bold
    status.deleted = cyan bold
    status.unknown = black  bold
    status.ignored = black bold

Sometimes a few further improvements for the pager extension are necessary. The following options should not be enabled unless paging is not working correctly.

    [pager]
    # Some options for the less pager, see less(1) for their meaning.
    pager = LESS='FSRX' less

    # Some commands that aren't paged by default; also enable paging
    # for them
    attend = tags, help, annotate, cat, diff, export, status, \
             outgoing, incoming

Enabling the described extensions should immediately lead to a difference when using the command line version of hg. Of these options, the only one that enables a new command is graphlog. It is recommanded that to use the command `hg glog`, instead of `hg log`, for a better feel about what commits are being based on.

#### Footnotes

### (13)

Please use the patch tracker only for patches which add new features. If you have a patch to submit that fixes a bug, you should use the bug tracker instead.

Next: General Guidelines, Previous: Building the Development Sources, Up: Contributing Guidelines [Contents][Index]