Subsections

2 Subversion usage rules

There are not many requirements put on us developers with respect to subversion usage, so we should actually be able to follow them. If you feel that any of these rules are stupid and as such should be changed, feel free do discuss them at our group meetings. However, until we agree on changing rules, we must obey them.

2.1.1 All checks should work after a commit

Before you make a commit to the trunk, you must make sure that all scripts, compilations, regression tests, documentation generations, or whatever needed in the project works as expected. There is nothing more frustrating than running into someone else's problems when you are about to solve that memory leak you have been looking for since 2pm yesterday. One way to make sure that your last commit did not break things is to actually have another pristine checkout of the project. This pristine working copy should only be updated against the repository for testing after your latest commit. If all checks run okay in this pristine tree you probably did a proper commit from your development working copy.

If you feel that you cannot fulfil this requirement there are two options. i) Create a private branch, fix whatever you are doing, and merge the changes into the main trunk when everything works again. ii) Ask the rest of the development team's permission to leave this rule for a very short time.

2.1.2 Do not check in personal debug code into the main trunk

If you must check in personal debug code, create your own branch and keep this branch and the main trunk in sync (see Appendix 1.1 on how to do this).

2.1.3 Commit often and do it minimalistic

Make sure that you stay up to date with the repository, i.e., commit often and remember to issue svn update.

When you decide to make a commit, make it small and to the point. By this we mean that commits should only contain whatever was needed to solve a problem or to add a feature. There is no use in committing trivial unnecessary changes into the repository such as stray blank lines or extra white space characters in the end of a line (CR - CRLF conversions are especially annoying and can be avoided by proper setup of your subversion environment).

2.1.4 Write a log message when committing

Log messages are useful for other developers when they want to know what was done in a commit. You may think that trivial changes can easily be “diffed” and thus need no log message. However, diffs requires more work than reading log messages, and remember, log messages for trivial changes are easy to write.

For projects that use trac for software project management there is a possibility to close or add comments to trac tickets directly when committing changes to the repository. This is done by writing a properly formatted log message, cf. A.20.

2.1.5 Set up proper subversion config file

Cut and paste the configuration setup from Appendix F into your subversion configuration file $(HOME)/.subversion/config

2.1.6 Use the $Id$ keyword to identify files

For all text files we modify and maintain, we must add $Id$ near the top of the file for easy identification of the file and its latest revision change. If you set up a proper subversion configuration file this requirement becomes trivial. The only thing needed then is to add $Id$ into source files.

2.1.7 Read and understand this document

This should not need to be a rule, but ... There are a few concepts which you may have neglected previously such as branches.

Read the branches section in the introduction and make sure you understand it. If you get confused, ask someone. Note that our release and branching procedure is defined in the branching section.

2.1.8 Project directory structure

In order to make future branching of projects under subversion control seamless, one must plan ahead when creating the project repository. In subversion this means that a proper project directory structure must be set up at the initial import of a project into subversion control.

The directory structure adopted for the project must always contain these three directories at root level

/trunk
/branches
/tags

The trunk directory holds the “main line” of development, the branches directory contain branch copies, and the tags directory contain tag copies.

This structure is needed for the branching procedure we are adopting (cf. Appendix 1.1), and the recommended structure in the subversion book.


2.1.9 Do not mess with the tags directory

Never make commits in the tag directory, it exists only for keeping track of tags7.