Commit Guides

Commit Policies

• When you start implementing a new feature, bug fix etc, always do it on the top of the main repository, not on the top of your last local commit.
• Read and follow the Coding Style conventions.
  • Use the standard LEMON copyright header.
• Be very careful not to add unnecessary files (but to add everything that is necessary).
  • Do not add generated files into the repository.
  • Do not add test files except very small ones.
• Do not do changes that are irrelevant to the main purpose of the commit
  • For example do not do whitespace changes and reformatting unless it is especially needed.
• If new files added, adjust the build environment config files, as well
  • the Makefile.am in the related directory for autotool,
  • the CMakeLists.txt in the related directory for CMake.
• Before you commit revise your changes (e.g. with hg status and hg diff). Be sure
  • not to do whitespace changes (Emacs' ediff or kdiff3 will help you in getting rid of them),
  • not to make reordering of declarations unless it is really necessary. If you must, do it in a separate changeset.
• Make sure that make check passes without any compilation warning for each commit with g++-4.3.
  • When files are renamed or new ones added also check the changset with make distcheck.
• At each point, changes should be "clean", i.e. to be self-contained, and not include any changesets that were false starts.
  • If you are working on a more substantial new feature or improvement, you probably want to commit frequently in order to make it possible the revert the changes that turn to be a bad idea later. Feel free to do that, but before you share your changes with others, you should clean your repository by removing the unwanted commits and concatenating those actually belong together. Here is a nice description how to do that: ​http://www.selenic.com/mercurial/wiki/index.cgi/TipsAndTricks.
• When you add a new algorithm or data structure:
  • Take the hassle to write a complete doxygen documentation as well.
  • Place the documentation into an appropriate doxygen module.
  • Update the NEWS file with a short announcement of the new feature.
  • Also provide an exhaustive test case, whenever it makes sense.
• When you port files from the SVN repository:
  1. Run the tools/lemon-0.x-to-1.x.sh and the scripts/unify-sources.sh scripts for all the files you would like to port.
  2. Check the renamings (e.g. source() and target() should be manually renamed to u() and v() for undirected graphs). See the Migration Guide for more information.
  3. Also port the related test files, if there are any.
     • Run the rename and unify scripts for the test files, too.
     • Print something to the output only if it really seems necessary. Do not print a message saying all test passed at the end of the output. (See #25 for details.)
  4. Add all necessary files to the repository.
  5. Check the documentation comments in the source codes.
     • Use \tparam commands for template parameter documentation. (See #29 for details.)
     • Remove \author commands. (See #39 for details.)
     • Remove \todo commands and create a trac ticket about them.
     • Check the usage of Lemon/LEMON. (See #103 for details.)
  6. Update the NEWS file with a short announcement of the ported feature.
  7. Make sure that make check and make distcheck passes without any compilation warning.
  8. Run make html and check the generated documentation of the new tools.

Commit Metainfo

User (author) identifier

Use your real name and email address in the following form.

Winston Churchill <wchurchill@dowling.gov.uk>

Use the same string for all of your commits.

Commit log

• The first line must be a self containing short but meaningful summary of the changeset. It should be no longer than 70 character.
  • If a changeset relates to a ticket, please always indicate the corresponding ticket id at the end of the first line of the log message, like (ticket #76) or just (#76).
• Then comes a longer description of the changes, if necessary. Do not list the changed files, but instead detail the nature of the changes.

Create Patch and Upload to Trac

• First create your changes and commit them to your repository. Then use the hg export command to create the patch files.
  • If you have a single changeset, you can export it as follows

    hg export --git tip > better-x-c5a48fc54f1a.patch
    

  • Should you have more changesets, export them one-by-one in separate patch files.
• When you upload a patch created from a changeset, please include its hash-id in the file-name. At least specify it in the attachment comment.
• Unfortunately Trac do not send notification on new attachments, thus please also write a separate short comment referring (see below) the changeset.
• When referring to a patch in the ticket, please use the hash-id instead of the file-name. (In the usual way, like [8ceb318224b1]). If you do so, it will be visible immediately whether or not the changeset you are talking about is already in the main branch.

Fix a bug

If you are about to fix a bug affecting more branches, you must place your changeset(s) on the top of the latest common ancestor of the branches. For example if you want to fix a bug existing in both the 1.0 release branch and the main one, you should do the following:

$ hg clone http://lemon.cs.elte.hu/hg/lemon#1.0 bugfix
$ cd bugfix
$ hg up default   <-- In fact, this is not necessary
[... fix the bug ... ]
$ hg ci -m 'Bugfix in BuggyTool, see #123'

Now merge it to the 1.0 branch

$ hg tag -l my-fix       # '-l' is important
$ hg up -C 1.0
$ hg merge my-fix
[... do some tests (e.g. make check) ...]
$ hg ci -m 'Merge bugfix for #123'           # Merge to 1.0

Finally, merge it to the main branch

$ hg pull http://lemon.cs.elte.hu/hg/lemon
$ hg up -C default
$ hg merge my-fix
[... do some tests (e.g. make check) ...]
$ hg ci -m 'Merge'                             # Merge is to main