A while ago, at a Geekdinner in fact, Serge and Paul asked me if i could explain to them how to use subversion – grassroots explanations, methodology and practice. The actual explanation never took place, but it made me see that a small explanation could be interesting to some.
Version control is an essential requirement to any and all software projects. Whether you back up manually while adding a date at the end of your files, or you use a proper tool, you need to do some form of version control. So might as well use an existing tool that makes versioning easier for you.
I’ll talk here about the methodology when using a centralized version control system.
I will not talk about the detailed commands, but rather of how go about versioning when you’re working with your team – something that may not be clear from the manual.
Subversion is the one i have most experience with, and is something of a de facto standard in the open source world. You can find the detailed commands here.
Getting started
Two scenarios here: you start a project, or you start work on an existing project.
If you start a project, you’ll need to create a repository.
I would advise you to create directories trunk, branch and tags within your repository. You’ll start working within trunk. I’ll explain later how the two other directories fit in.
As a rule, you create a user for each of your team mates – this allows you to keep track of who the hell has done what. And to regulate accesses – who can commit, who can’t.
After that, you need to add every source you create.
If you start work on an existing project: this means you check out a source tree from an existing repository.
Trunk
The latest state of your source directory is normally to be found under the trunk directory.
While you’re working, you keep all your modifications on your computer until they make a coherent whole, that compiles and passes your tests. Before you commit it into the repository, you check what has changed since your last addition – and if needed, you merge some sources, and you make sure everything compiles and works.
This is a must: in most projects there is a regular build process to make sure all additions compile and build. If you insert something that doesn’t compile or interact well with other features, bad karma on you. And needless to say that removing a teammate’s work from your version without notice is a definite no-no.
(No permanent harm done, since this is versioning after all, and all can go back to previous version, but it might affect your rep within the team)
Branches
Branches are useful in two situations.
The first and foremost is when you put your project into production (or make it available for use). When you deem a version ready for release, you tag and branch.
Branching means you copy the whole of your source tree under the branch directory. Tagging means basically the same, but in the tags directory. It’s the use of those copies that is different.
The branch you create contains a copy of the code you put in production.
Why is that useful ? Well, development continues on the trunk. Imagine you need to introduce a fix or patch to the application that is currently in production ! For that you need that version of production, and not the one with new (unfinished) features that is in trunk.
Whenever you need it, you can check out the production branch you’ve created, and fix and patch on that version.
The production branch will be of use to you until you put an entirely new (major) release into production, and create a new production branch.
A second situation where a branch can be useful is when you decide to prototype a possible solution that might not be applied to production. Or if you’re developing a feature that has so many dependencies that it will stop other developers from continuing their job. Then you can branch, develop and commit at ease, and merge with the trunk when ready or desirable.
Tags
Tags, as said, are snapshots of your source tree. Whenever a significant milestone is reached, or any other time that should be recorded, you copy your source tree as a tag (and name). It is used as much to keep track of the code as to label a particular step in your development.
(imho ‘leaf’ would have been more in keeping with the whole poetic tree metaphor than ‘tag’, but there you are)
Tags are useful when managing the existence of both a production branch and development in the trunk at the same time. Any fix you apply on the branch should also be merged into the trunk ! Otherwise any error you thought eradicated will resurface in the next release. Not very good.
So a way to keep track of this is to make ‘merged-
Tags and versions (update)
How to name your tags ? Well, simple: your tags are your version numbers.
Convention for version numbers in the open source world are described here.
What we did in my last project is to increment the minor number when releasing into production. The tags on the branch kept the previous minor number, and the build was incremented. The tags on the trunk had the next minor number, and for all following tags the build number was incremented.
For releases in test, we used the RC notation (release candidate) – version-RC1, if that needed a fix, the next release in the test environment was version-RC2 and so forth.
Now this is a matter of convention: you can decide with your team how you’re going to proceed (if you prefer, can give your releases animal names).
Comments
As in any other step of the development, you want to add relevant comment. When you commit code, when you tag, when you branch. This might help you make sense of what you did later on.
Well, i hope this was useful to some. A subversion or other manual will not always convey what some terms actually mean. Let me know if some of this needs elaborating, or if you have another interpretation.
The whole of the Rails community has now shifted towards a decentralized versioning tool, git. I’ve used git on my own code, and i think i understand the concepts, but have never used it in collaboration with a team, so i’ll not make a post about it until i have more experience. Any others volunteering ?
