Translate Toolkit & Pootle

Tools to help you make your software local

User Tools

Commit guidelines

This page describes some basic rules for committing to the version control system. Although these are just guidelines, they should be useful most of the time. Above all, let's make it work. If following these guidelines will cause more harm than good, obviously we need to keep our main goals into account.

Where/when to commit

As far as possible we try to work on the trunk to avoid unnecessary merging activities. Note that while trunk is in preparation for release (if we haven't branched to maintain a stable release yet), some things are probably better of in branches rather than in trunk. Discuss it on translate-devel.

Most of the time, big changes probably need to be reviewed before a commit. This might happen through bugzilla, the mailing list or private arrangements. Sometimes just explaining to somebody else what you do is useful to catch the last issue you might have missed.

Always test the effect of your change on the unit tests. Be aware of the coverage of the unit tests for the piece of code you are working on. In most cases you probably want to add tests for your new code as well.

Commit messages

Always supply a useful commit message that describes the change. Remember that your message will often be read out of context (changelogs, RSS feeds, version control logs for the file, etc.). Try to keep in mind what the reader will want to know.

A detailed explanation of what the code does, is probably more suited in the code itself - another developer won't read the commit log to work out how the code works.

If your change fixes a bug in Bugzilla, mention the bug number (and mention the revision number in the bug). If you are reverting a previous commit, mention the revision number that is being reverted.

If your commit message includes a list of different changes, you are most likely committing too much in one commit. Check the next section on what to commit.

What to commit

As far as possible, try to commit individual changes in individual commits. Where different changes depend on each other, but are related to different parts of a problem / solution, try to commit then in quick succession.

Never commit across product boundaries in a single commit (for example, don't commit a group of files where some files belong to Virtaal and the others to Translate Toolkit). It might cause problems with changelogs, and is indicative of a compound change that really involves different issues in one.