Source code version control is a must for software development nowadays. There are dozens of such tools now, and the distributed SCM is getting more and more popular: Git, Mercurial, Bazaar, etc… . Yet I’m not going to discuss which tool is the best, or why tool X is better than tool Y in this post. Rather, this post attempts to outline some good practices of svn , the client tool of Subversion (still the most popular SCM at the moment) .
Well, the practices here is all about ‘commit’ action, i.e. the ‘change commitment’ when modifying some files. Because they are the most relevant actions from client side of SCM, in my opinion. Actually, the principles here are similar to other source control tools, not only Subversion, you get the idea.
Precise comment for every commit
The second most annoying thing with SVN commits is blank comment. Even if the developer is working alone, he/she will not be able to easily track down what a certain commit did . It’s worse when some unexpected behaviour occurs after some commits: blank comments do not help anything and the developer have to look in the code change of each revision to get some clues about what can be the culprits.
On the contrary, if the comment says what the change intended to do, it will be much easier to guess which changes can cause the affect, and it will save *days* to track and fix the bug. The practice here is: the more precise the comment is, the more helpful it is to save time for tracking the changes. Lengthy comments are better than blank comments, but they are also not so good because sometimes they can be confusing or even be lies ! So the commit comment should be exhaustive enough to express what the change does, but also short enough to be concise (usually one line is sufficient) .
Don’t break the (mainline) build !
As a developer in modern days, you probably heard of this line before ” Don’t break the build! ” , or “The trunk is broken! Somebody should fix it ASAP” .
Yes, breaking the build is the most annoying thing ( undisputed! ) when working in a development team using source control. Because not only does it waste the committer’s time, but also it slows down other people. For example, to detect whether it is really broken, is it safe to update source code or commit their own changes?
If they just wait for the fix, it slows down their productivity right away. If they have to spend time finding the error to fix it or bypass it (workaround), they will be easily get mad at the committer or get frustrated . If they are polite and just find him/her to ask nicely about the build, that’s already wasting time (not because of their carelessness! ) . And the longer it is broken, the more trouble it causes.
In short, breaking the trunk is a habit that will quickly earn you the hatred of other developers . So , to avoid that, before commiting code make sure to double check: update latest code, make a clean build (run all tests if exists) , verify if you deleted some folders or added some new files. That just takes a little time, it’s nothing compare to the trouble of breaking the build.
Commit as soon as a logical unit changes
“How often should I commit?” is a frequent question of beginners of a certain source control management tool. For Subversion (and probably for most of SCM), the typical answer is : “You should commit each time your changes represent a logical unit, i.e. some change that makes sense.” .
If committing too rarely, there will be a high probability that there are already a lot of modification since the last update of your code, and maybe you have many files to commit too. Thus it’s likely to have code conflict, need to merge/revert/overwrite, not to mention having to merge the conflicts again and again, let alone breaking the build.
If committing too often, it’s better. It is recommended for experienced developers. But there is a chance some developer can think that the commiter is just trying to gain attention, or even worse: trying to claim credit on other people’s efforts. So, avoid trivial commit such as a single file with 1 or 2 lines formatted. Sometimes a tiny change is acceptable, like fixing a typo in a test which breaking the build. Don’t be shy then, nobody will be mad at you for being precise. The point is the commit makes an atomic action better than nonsense, and the owner should feel easy when writing comment for it (see the first practice in this post). For example, after your commit (revision N) other developers can know that revision N fix a bug, while revision N-1 is buggy.
If you dedicated one single commit for the actual finite logical unit, it helps when somebody just scroll back the changelog or want to track some bug, or to revert to another revision. There is no point in seperate a logical change into multiple commits, each per file, if the intention (indicated by comment) is the same. The comment is a very good indicator for ‘logical unit’ change. If your SVN comment looks like “Fixing bugs #1234 user registration, and #6789 duplicate orders” or “Fixing bug #4321 login; and optimize performance” then you should’ve used two commits.
Avoid using Subversion as a backup tool
I’ve heard this question too often: “Have you put your code safely on SVN?“. That’s an unnecessary question. Storing code to an SVN server is not meant for safety, i.e. for fear of losing it. You are talking about something else, and that’s called backup. Yes, a faulty hard drive can still make you lose all your work, of course. That’s why you have to do backups, of course, but they don’t have anything to do with versioning.
Hence, committing to the repository once a day, before taking off home, e.g., is not an acceptable practice, especially if you work in a team. Doing that would be like making a daily backup. An SVN commit, instead, has to have a meaning of some sort, not just “Ok, let’s store to the SVN server the work of today“. Moreover, sometimes, if the schedule is tough and the cooperation is tight, you need to commit very often so your peer will keep up with you all the time, and not just find out, at evening, that he’s got dozens conflicts after checking out your code.
Less branch and merge
Subversion supports branching, but it’s not so good at merging back the branch to the trunk. That’s one of the reasons that distributed SCM rises. There are some ways to handle branches, but my favourite is to minimize the number of them. Again, don’t use branches as backup, or daily-work-pastebin. If you need a marker for stable build, SVN already supports ‘tag’ .