The Dos and Don’ts of Subversion Control System

The Hugin community is a warm and welcoming place. From our community’s charter: We often encourage users to become contributors by proactively offering them SVN write access. Such access to Subversion (SVN) can be intimidating. Fear not, version control systems are the tool to avoid irreversible unintentional damage. When a potential contributor asked the question again I did not find an answer on the web, so I set out to write this article.

Repository Areas and Policy

The best-practice SVN repositories are divided in three areas: trunk, branches and tags, each of them with different purpose.

That’s enough for Hugin. Combined with the intrinsic characteristics of version control it makes our repository a safe place to experiment. So far we did not need repository policies, just use good old common sense.

Larger projects may have written policies about repository status. Some depend critically on areas of their repository building at all the time and at every revision. Before committing to such repositories, changes must undergo all sorts of tests, often specified in written documents as well.

Trunk

Trunk is the famous bleeding edge. Most developers will be active on trunk, fixing bugs and adding features incrementally. Mistake happens where people work. No blame. Bugs can be often identified by stepping back a few revisions and comparing to HEAD (the latest revision).

Branches

Branches are copies, mostly of trunk, that started at a specific revision. From that point on, the branch differs from the original. They can have many purposes, and the specific dos and don’ts depend on that purpose.

• If a branch is meant for release do fix bugs and don’t add new feature.
• If it was started by a developer to develop a new feature, ask him first before fiddling with his work.
• When in doubt, start your own branch. Branches are cheap in Subversion. Most Google Summer of Code projects start their life as a separate branch.
  

Development branches eventually merge into trunk and become obsolete. Release branches are superseded by later release branches. On occasions parallel branches make sense and are maintained either over a transition period or indefinitely, and sometimes a branch takes a completely different meaning and becomes a fork.

Tags

Tags are moments in time that have particular meaning. As a general rule, don’t touch existing tags. Create new ones.

Repository Status and Release Lifecycle

Some projects have different repository status during the release life cycle. A temporary freeze on new features might apply to allow for the polishing of code toward release, in which case do commit translations and bug fixes but don’t commit new features. If you are unsure of the current lifecycle status of the project you contribute to, just ask. On Hugin we are currently in a freeze, working toward 0.8.0. But we tend to be tolerant and won’t refuse other contributions. We might adopt a more formal process in the future, branching out the feature-frozen code for release, but at the moment we lack the resources and don’t feel the need to maintain separate release and development branches.

The Dos and Dont’s

Dos	Don’ts
Check out the latest revision before start working, and check your changes back in as soon as possible.	Don’t use svn locks. Commits in subversion are transactional and locks are almost always unnecessary.
Commit often, one change at a time. Easier to read and debug.	Don’t include multiple changes in a single large commit.
Look at the diff before committing, make sure you can answer the question: what are you changing? You’ll need the answer for the next point.	Don’t tidy up the code while making changes. If tidying up is necessary, do it in a separate commit (see Bruno’s comment).
Document changes in the commit message, use the -m switch in the command line or the entry field provided by TortoiseSVN or other SVN-GUIs.	Don’t leave the message field empty. If the change requires more than a few lines of explanations, consider breaking it down into multiple commits.
Reference tracker tickets in the comment when applicable.	Don’t fill the message field with prose. If the nature of the change requires a lot of explanations (e.g. new API), provide documentation in separate file(s) and refer to it.
Use svn:externals or scripts to fetch and unpack external dependencies.	Don’t commit external dependencies (e.g. “SDK”) to the repository.
Discuss conflicting choices and seek consensus on the hugin-ptx mailing list. Consider adding alternative functionality rather than replacing existing one.	Don’t override other committers code just because you disagree with their solution.
Consider branching when the development work you initiate will take more than a day or two to complete.	Don’t regret the code lost because you did not commit it right away.
Test your changes locally before committing. If you must leave unfinished or untested work, wrap it in an always false condition so that it won’t affect other users.	Don’t commit changes without having them tested locally.
Keep in mind that the code is for multiple platforms. Ask users of other platforms to check if your changes affect their platforms adversely.	Don’t ignore other platforms and silently break the code for them.
Ask on the hugin-ptx mailing list for advice. If you are unsure whether you should commit, provide a patch that other users can apply and test.	Don’t be shy. Your contribution is always welcome. If it breaks something, we’ll work together to fix it.
Give credit where credit is due. If adding to SVN code from a third party patch, mention the third party as originator of the code. If making a change on user feedback, mention the user.	Don’t commit third party changes without testing and understanding what they do first.
Keep files that do not require version control in appropriate resources such as Flickr, Vimeo, or webspace that is donated to the community.	Don’t clutter the repository with files that do not require version control and use a lot of space/bandwidth, such as podcasts and presentations.

Last but not least: do use your common sense and don’t be shy to question the current way of doing things. You might have a point, and neither you nor we will know it unless you bring it to our attention. If you feel something important is missing in the above list, you are invited to comment.