Good source management

Troy Hunt writes on The 10 commandments of good source control management. They are:

  1. Stop right now if you’re using VSS – just stop it!
  2. If it’s not in source control, it doesn’t exist
  3. Commit early, commit often and don’t spare the horses
  4. Always inspect your changes before committing
  5. Remember the axe-murderer when writing commit messages
  6. You must commit your own changes – you can’t delegate it
  7. Versioning your database isn’t optional
  8. Compilation output does not belong in source control
  9. Nobody else cares about your personal user settings
  10. Dependencies need a home too

Read Troy’s article for all the details. I’d like to elaborate on a few.

VSS – stop using it. Totally. “Back in the day” I worked at Metrowerks and they made the Mac version of Visual SourceSafe… or as it was jokingly called, SourceSuck. There were a lot of cool things about it, and sometimes I still think the ability to lock can be useful. But the main repository was constantly down, constantly being rebuilt. It was terrible. Thankfully tools have progressed since then. Subversion is great. I haven’t had the opportunity to try git yet, but that it’s maturing is a good sign.

Commit early and often. Very true. It always gives you a rollback point. A lot of people are afraid of this for whatever reason, especially fearing the merge. Understandable, but it’s just part of life and certainly using version control will help ease the pain — if you use it right. So put your work into a branch, every so often merge in changes from the trunk to keep you building and current, but still doing your thing. When it’s time for you to go back into the trunk, the merge won’t be so painful. If you must reconcile, you must. It happens, but it’s not the end of the world. Maintain that history, give yourself the protection that version control is for.

Going with this, #10. Over time I’ve changed how I lay out my Subversion repository. The basic recommended layout is:


and while that’s a good start, I expanded upon it:


Branches hold branches, labeled in a manner that describes what the branch is about. There’s no need to get too formal about the branch name, so long as it along with the commit message adequately describe what’s going on. Sandbox provides a place to play, perhaps you wanted to write a little testbed application that is relevant to the project, this is where to put it. Why put it into the repository? See #2, along with just all the good reasons for versioning source. Tags is broken down into a little more organization. Development tags are tags defined to ease development, like you’re about to make some big change and want to demarcate a clear rollback point. Build tags are tags made during your build cycle, perhaps by the automated build server, to of course denote a particular build. Candidate tags are tags to say “this is a release candidate”, and these tags are made from a build tag (e.g. “svn copy tags/builds/ tags/candidates/1.0.0FC1”). Release tags then are the actual public releases, made from the candidate tags (e.g. “svn copy tags/candidates/1.0.0FC2 tags/releases/1.0.0”). This hierarchy of tagging allows a tracking of history. Trunk of course is the main development trunk. The vendor area is for any sort of third party product that is relevant to go in. I like to put the archive, as downloaded, into the vendor/archives/ area (e.g. the .gz or .zip or .dmg or whatever), so the archive as received is maintained. Into vendor/src I then like to put the expanded/opened distribution, but with minor modifications. For instance, they didn’t make a clean distribution and included .svn folders, or build products or other things that are irrelevant or dirty things up, or renaming the top-level folder to something more descriptive (e.g. from “distro” to “boost-1.46.1”) ; it should be as close to the original distribution as possible, just cleaned up. From there, the /vendor/src/whatever/ is svn copied into the /trunk. This allows the original distro to remain clean, but if say it’s necessary to make changes to the local version we can do that without risking dirtying the original distribution.

Of course, this setup may not work for you and your projects, but over the years it’s what has evolved to work for me and my needs.

#8 and especially #9 – yes. Please stop checking in your cruft.

Remember, version control is there to help us write better code. Not directly, but once code is written it will always have to be maintained. History is a part of that maintenance cycle. The more relevant history we can preserve, the better off we can be in the long run.

2 thoughts on “Good source management

  1. In 2004, I started work with a team who had never used anything but VSS. I had never used VSS, but loved Subversion which I’d been using for a couple years. How different/bad could VSS be, I thought? I gave in. What a mistake! We’re on TFS now, but even that is often a funhouse-mirror-reflection of a sane, modern VCS.

    For my own projects, I’ve been using Mercurial. You might give it a look, if you haven’t. It’s a pretty close race between Mercurial and Git, in my opinion, assuming you don’t need any of the more exotic Git features. I also found Hg very easy to learn, coming from Subversion.

    That said, it’s been my experience that getting your colleagues to adopt and grok the version control “religion” is the key issue. The specific version control tool is not nearly as important. That is, unless your VCS is so painful or broken that developing good habits with it is difficult, as it was with VSS.

    Thanks for sharing your repository layout!

    • VSS was good at the time (tho there’s always the Perforce lovers too… never got to use it myself, but those that did loved it). I honestly haven’t spent too much time with Mercurial or Git (tho I end up at often), mostly because the day job requires Subversion and my personal repositories have been using svn for a long time so… just haven’t had reason to change.

      I just wish people would use their VCS beyond a glorified backup and sharing solution… so that the code is preserved somewhere, and that we all get the changes. There’s so much more it can do and is useful for. If nothing else, the “svn blame” command is so useful when the build breaks. 😉

Comments are closed.