Category Archives: Uncategorized

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:

/trunk
/branches
/tags

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

/branches
/sandbox
/tags
    /builds
    /candidates
    /development
    /releases
/trunk
/vendor
    /archives
    /src

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/1.0.0.005 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.