Instruction: Using Subversion and the commit policy

Subversion uses a client-server architecture. The Subversion project provides the server, a standard command line client and a set of utility command line programs for administering Subversion repositories. There also exist a number of independent Subversion clients that are maintained outside the Subversion project. It is important to realize that Subversion is configured both on the server side and on the client side. The configuration on the client side affects how Subversion clients will interact with Subversion servers and repositories so it is important to set it up correctly.

Read the O'Reilly Subversion book  Version control with Subversion.

Subversion client configuration

The current Subversion server version is 1.4.6. Make sure you are using a Subversion client that is compliant with the current server version.

Use this client-side config file. This is where you should put the file:

Linux~/.subversion/config
Windows%USERPROFILE%\Application Data\Subversion\config

Make a copy of your old "config" file first if you want to be able to switch config files later.

The important thing to have in the client-side config file is:

enable-auto-props = yes

and:

*.e = svn:keywords=Author Date HeadURL Revision;svn:eol-style=native
*.ecf = svn:keywords=Author Date HeadURL Revision;svn:elo-style=native

The most important property is eol-style=native which causes eol to be handled correctly for different platforms.

Subversion keyword expansion

All Eiffel files should begin with the following indexing clause:

indexing
    description: "<Description of file goes here>"
    authors: "<Full name of original author(s)>"
    copyright: "<Copyright notice>"
    license: "<Name of software license>"
    date: "$Date: <Expanded by Subversion> $"
    revision: "$Revision: <Expanded by Subversion> $"
    url: "$HeadURL: <Expanded by Subversion> $"
    last_changed_by: "$Author: <Expanded by Subversion> $"

Note that all keywords inside '$' characters will be expanded by the Subversion client. Note also that the first four lines are not expanded. The line beginning with "authors:" should contain the name of the ''original'' author(s) of the file. The Subversion keyword "Author" is expanded to the name of the person who last modified the file in the Subversion repository.

Important note: If a file was added and committed to the repository from a client that didn't use the above configuration file the svn property for keyword expansion for that file will not be set. The property can of course be set manually afterwards, but that is a nusiance. Please make sure you use the configuration file above.

Commit Policy

Read and understand the following commit policy (adapted with some modifications from the  KDE project's commit policy):

1) Think Twice before Committing

Committing something to SVN can have 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. This is relatively easy for commits to single files but it can also be a significant amount of work for bigger changes. The baseline is: Be aware of the consequences of your commits. Take time to think about them before committing.

2) Never commit code that doesn't compile

Compile the code and correct all errors before committing. Make sure that newly added files are committed. 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. Be especially careful if you change the build system.

3) Test your changes before committing

Start the application affected by your change and make sure that the changed code behaves as desired.

Run unit and regression tests, if available.

4) Double check what you commit

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

5) Make atomic commits

SVN has the ability to commit more than one file at a time. Therefore, please commit all related changes in multiple files, even if they span over multiple directories at the same time in the same commit. This way, you ensure that the source code stays in a compilable and consistent state before and after the commit.

6) 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.

Take a second to think up a short but descriptive message. Try to fit the message in a single sentence. At some point in time we may wish to automatically generate e-mails for certain commits. The log message should be able to be used as an e-mail subject line. The log messages can also be extracted and used for a release changelog.

7) Use Trac ticket system numbers

If you fix bugs or implement a something described in a ticket reported in the Trac ticket system, add the ticket number to the log message using the syntax #NNN where NNN is the ticket number. In order to keep the ticket system in sync with SVN, you should also mark the ticket as fixed in the ticket system.

This doesn't mean that you don't need an understandable log message. It should be clear from the log message what has been changed without looking at the bug report.

8) Special keywords in SVN log messages

When you commit changes to SVN you will be asked for a description of your commit. There are several special keywords defined that you can use in this description. These keywords are always uppercase and followed by a colon. Each keyword should be placed on a line of its own. The following keywords can be used.

  • BUG: #NNN <Log_message> The bug with the given ticket number has been fixed.
  • FEATURE: #NNN <Log_message> The feature with the given ticket number has been implemented or modified.
  • GUI: #NNN <Log_message> Indicates a visible cosmetic change in the user interface that can't be classed as a feature change.
  • DATA: #NNN <Log_message> A data related modification. This could be test data or reference data meant to be part of the delivered system.
  • DOC: #NNN <Log_message> A documentation related modification. This refers to end user documentation that is meant to be part of the delivered system. Examples are system presentations and user manuals.
  • QA: #NNN <Log_message> A Quality Improvement related modification. This could be code refactoring or reorganization of source code. It could also mean the modification of small utility tools used for building or testing the system. Or modification of "readme.txt" files or development related documentation such as specifications or test manuals.
  • CM: #NNN <Log_message> A CM related modification. This typically has to do with modifications to the build system or packaging tools.
  • COSMETICS: #NNN <Log_message> Indicates cosmetic changes in source code or other files like fixed indenting, code layout or spelling errors.

These keywords can be used to automatically extract entries for the release changelog, so it makes sense to use them even if you don't have a ticket number for the feature. In that case you simply don't write a ticket number.

It is also valuable if the message tells which part of the system has been modified. Since SVN supports atomic commits of multiple files you may commit changes to a set of files in completely different parts of the repository structure it is very valuable to write what part of the system was the main focus of the modification. Eg:

GUI: #76 Fixed border colors in Administration module

9) Don't mix formatting changes with code changes

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

10) Announce major changes in advance

When you plan to make changes which affect a lot of different code in SVN, announce them on the mailing list in advance. For instance, changes in libraries might break other code even if they look trivial, e.g., because an application must also compile with older versions of the library for some reasons. By announcing the changes in advance, developers are prepared, and can express concerns before something gets broken.

11) Take resposablity 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.

12) Don't use SVN as a temporary backup

Don't use SVN as a general temporary backup area for work in progress. If you really need a temporary space in SVN for keeping work in progress use the dedicated "wrk" directory for that code.

13) Tags and branches

Don't create tags or branches in the repository before discussing it on the mailing list with the other developers.

14) Don't add generated files to the repository

Files generated at build time shouldn't be checked into the repository because this is redundant information and might cause conflicts. Only real source files should be in SVN.

15) Don't use SVN keywords in source files

SVN keywords like Id or Log cause unnecessary conflicts when merging branches and don't contain any information which wouldn't be available in the SVN repository anyway.