2.2. Committing

Prev		Next

2.2. Committing

2.2.1. General Principles

Testing: Mercurial allows you to commit locally, which means you have a faster workflow. However, as a core developer who will be pushing changes to the master, you should still try to ensure that all your commits are consistent in themselves, that is that every point in the history of the repository builds and runs. It is possible to re-shuffle the commits you’ve made later using Mercurial Queues, but only if you haven’t pushed the commits anywhere else beforehand. Usually it’s better to try to keep your commits consistent all the time. So, do commit often, because a rich history is always best, but do at least check that everything compiles and runs before creating a new commit.
Cohesive commits: Your commits should be as focussed as possible on a single subject. Try not to commit changes for multiple purposes at once, it makes it much more difficult to pick apart those changes later if needed. And most importantly, never ever commit a bugfix and a feature change in one commit, unless changing the feature was the only way to fix the bug (in which case it can only be fixed in the unstable default branch).
Unnecessary changes: Although it can be tempting to "tidy" code, fix indenting, standardise etc, you should generally avoid doing this for its own sake. If you’re changing the code anyway, by all means fix any formatting and standardisation issues in the area in question while you’re at it. But purely aesthetic changes should never be committed on their own, because all of them can potentially make merging real changes - across branches and accepting patches - far more difficult because of conflicts caused simply by trivial formatting changes.

2.2.2. Committing Bugfixes

Bugfixes should always be committed to the current stable branch (assuming they affect it) first. So for example at the time of writing bugfixes should be committed to the v1-7 branch. These bugfixes will be merged forwards into the default branch periodically. The reasons for committing to the stable branch first and merging forward, as opposed to committing to the default branch and picking commits to transplant back to the stable branch, are many:

It encourages primary testing and early committing on the stable branch, which is where fixes are needed most urgently anyway.
Merge conflicts always happen in the unstable branch, not the stable branch. This is better again because the stable branch is the most important to keep as clean as possible
Merging is automatic. You always want to merge ALL changes from the stable branch into the default branch, there is no human error involved in selecting what changes to merge. If you cherry-pick fixes to port to the stable branch, you have to make sure you don’t miss anything, make sure you don’t accidentally include an interface change, etc. And if someone has committed a combined fix and an API change in one commit (see below) it’s a mess.

2.2.3. Committing New Features and Breaking Changes

Any new feature, or a change which changes either the API or the behaviour within the existing API, must always be committed to the default branch (often referred to as unstable).

Prev	Up	Next
	Home