T2 SVN commit tutorial

Think twice before committing.

Committing something to SVN has serious consequences. All other developers will get your changes once they are in SVN, and if they break something, they will break it for everybody. All commits will be publicly available in the SVN repository forever.

On the other hand SVN allows one to revert changes, so it's possible to recover from mistakes.

The baseline is: Be aware of the consequences of your commits. Take time to think about them before committing.

Never commit code that doesn't compile.

Compile the code and correct all errors before committing. Make sure that newly added files are comitted. If they are missing your local compile will work fine but everybody else won't be able to compile.

You certainly should make sure that the code compiles with your local setup and platform. You should also consider what consequences your commit will have for compiling on another architecture.

Be especially careful if you change the T2 build system, i.e. files in the directories scripts/ and source/.

Test your changes before committing.

Build the packages and start the application affected by your change and make sure that the changes behaves as desired.

Double check what you commit.

Do a "svn up" and a "svn diff" before committing. Take messages from SVN about conflicts, unknown files, etc. seriously. The "svn diff" will tell you exactly what you will be committing. Check if that's really what you intended to commit.

Always add descriptive log messages.

Log messages should be understandable to someone who sees only the log. They shouldn't depend on information outside the context of the commit. Try to put the log messages only to those files which are really affected by the change described in the log message.

In particular put all important information which can't be seen from the diff in the log message.

We have some basic policies for commit messages: The changes are indented one tab and the changes enumarated with an asterisk (*):

When the author is not the committee the original author must be named in the first line:

Typical commit messages are:

For the case of added or updated packages we added a helper script

Respect special commit policies set by the release plans.

Respect the policies of the current release phase and avoid commiting new features and code shortly before a planed release.

Source control systems are not a substitute for developer communication.

When you plan to make changes which affect a lot of different code in SVN, announce them on the mailing list in advance.

Changes which affect a lot of code in SVN, like making use of a new feature in the libs, might break other code even if they look trivial, e.g., because an application must also compile with older versions of the libs for some reasons. By announcing the changes in advance, developers are prepared and can express concerns before something gets broken.

Take responsibilty for your commits.

If your commit breaks something or has side effects on other code, take the responsibility to fix or help fix the problems.

Don't commit code you don't understand.

Avoid things like "I don't know why it crashes, but when I do this, it does not crash anymore." or "I'm not completely sure if thats right, but at least it works for me.".

If you don't find a solution to a problem, discuss it with other developers.

Don't abuse your SVN account to push in changes with which other developers disagree.

If there is disagreement over code changes, these should be resolved by discussing them on the mailing lists or in private, not by forcing code on others by simply committing the changes to SVN.

If you commit bugfixes, consider porting the fixes to other branches.

Use the same comment for both the original fix and the backport and include the original revision ID. That way it is easy to see which fixes have been backported already.

If you fix bugs reported on the bug tracking system, add the bug number to the log message.

In order to keep the bug tracking system in sync with SVN, you should reference the bug number in your commits, and close the fixed bugs in the bug tracking system.

Make "atomic" commits

SVN has the ability to commit more than one file at a time. Therefore, please commit all related changes of multiple files, even if they span over multiple directories at the same time in the same commit. This way, you ensure that the repository stays in a compileable state before and after the commit and change-sets easy to merge or revert.

Don't mix formatting changes with code changes.

Changing formatting like indenting or whitespaces blows up the diff, so that it is hard to find code changes if they are mixed with reindenting commits or similar things when looking at the logs and diffs later. Committing formatting changes separately solves this problem.