Clone wiki

thg / developers / contributing


If your changes are simple enough to be contained within a few changesets, it is preferable for patches to be sent to the thg-devel mailing list. This expedites the review of the patches, and allows other developers to comment directly on your changes. If possible, please don't attach your patches. Developers have to strip them manually to import from maildir.

It is typically easier for everyone (including yourself) if you proceed as follows:

  • check in your fix locally, give it a meaningful commit message explaining what you are fixing,
  • then use the email tool (from the TortoiseHG synchronize dialog) to send it to this list.

Remember to use git patches if you are submitting binary files, symlinks, or permission changes. Setting [diff] git = 1 in your Mercurial.ini or .hgrc makes this selection permanent and global.

You should indicate to which branch your patch applies (stable or default). Bug fix patches should be based on stable unless the bug they address is only on the default branch.

Large changes that do not fit within a few patches could be published in a public repository. If you don't have your own server, you can use one of the free hosting services on the net. Obviously we prefer Bitbucket. Just open an account, fork the appropriate repository, and start hacking.

Please also note that TortoiseHg has adopted the unix line end style of the Mercurial sources, even though we are targeting the Windows platform.

General Guidelines

The Mercurial wiki has a good page with suggestions for contributing patches. In general these are also applicable for TortoiseHg.

TortoiseHg specific guidelines can be found in CONTRIBUTING.txt

Guidelines For Commit Messages

  • If your change is in response to an issue in the bug tracker, you should use trac style commands in your commit message:
    • Syntax: verb [# or issue or nothing] number
    • Verbs: close(s), fix(es), reopen(s)
    • Examples: fixes #12, closes #20, reopen issue 15
    • The Bitbucket issue will get updated when your change pushed
  • Make sure your commit message starts with a reasonable one-line summary.
  • Keep all lines, especially the summary line, below 80 (72 preferred) characters.
  • If you are going to give more detail in the commit message, please keep a blank line below the summary line, right before the start of the detail.
  • Prefix the commit summary with a short text identifying the area the patch is targeting (see below).
  • We prefer no capitalization in the summary line, unless required by quoted variable or file names.

Here's some examples by peso to help illustrate the guidelines:

Summary Prefixes

The standard prefixes we've used so far (extracted from the revision history) :

  • cmenu - context menu extension
  • overlay - overlay icons extension
  • thg - generic change that affects thg
  • <module> - changes made to <module> in tortoisehg/thg/ subdir
  • contrib/<module> - changes made to <module> in contrib subdir
  • wix - on binary installer (WiX, config files, etc)
  • setup - changes in
  • py2exe - related to py2exe (in
  • icons - icon maintenance
  • doc - contributions to the documentation
  • nautilus - nautilus integration

Please note that there's no standard per se, just use your common sense if you encounter a new area, or even revise an existing one. Please refer to the changelog of TortoiseHg if in doubt, or consult the mailing lists.

The general idea is to be able to identify the areas that a patch targets, while consuming the minimum amount of characters on the summary line.