• Subscribe

    Subscribe to This Week In Panospace by eMail.
    Subscribe in a reader
  • License

    Creative Commons License
    This work is © 2008-2012
    by Yuval Levy
    and licensed under a
    Creative Commons License.
  • Entries

    March 2009
    M T W T F S S
    « Feb   Apr »
     1
    2345678
    9101112131415
    16171819202122
    23242526272829
    3031  
  • Archives

The Dos and Don’ts of Subversion Control System


Groundhog protecting his holeThe 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.

6 Responses

  1. The only thing I’d add is that in addition to keeping unrelated code changes in separate commits, keeping formatting changes separate is just as important.

    i.e. although it seems like a good idea to tidy up as you go along (fixing formatting, whitespace, empty lines etc…), this makes the commits really difficult to read.

    So: tiding up is a separate job, when needed it should be done independently of code changes.

    A good habit is to look at each change before you commit, on the command-line this is easy:

    svn diff | vim –

  2. @Bruno: indeed, your addition is an important one and looking at the diff should be mandatory before committing. TortoiseSVN has it easily accessible from the context menu. I added it in a Do/Don’t line.

  3. Oh, and if committing somebody elses work, credit them in the commit message, something like this in brackets:

    Fix for incorrect value of pi (Mronjink Plognholisk)

    These messages end up in the ChangeLog which is the only place where most contributions get noted. Feel free to credit anyone even if they just commented in a bug report (not very diligent about this myself).

  4. @Bruno: added “give credit where credit is due”.

  5. You write “Branches are cheap in Subversion”. They are not. I needed Git to come along to see why I hardly branched with Subversion before.

  6. @Sebastian: Git, Mercurial and the other distributed version control system are cool indeed, although I find the user interface and the cross-platform support still lack maturity.

    While there is some overlap, it is not 100%. There are plenty of applications for which a combination of distributed and traditional version control system is a superior solution to using either of them.

    When judging the choice of tools one need to understand the past. Hugin has grown with CVS first and then with SVN as Sourceforge graciously offered that too in its free infrastructure. I don’t think that the project has a need to migrate to Git or Mercurial.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s