SVN best practices

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 work­ing alone, he/she will not be able to eas­ily track down what a cer­tain com­mit 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, break­ing 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 com­mit?” 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 com­mit each time your changes rep­re­sent a log­i­cal 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 pre­cise. 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 revi­sion N fix a bug, while revi­sion N-1 is buggy.

If you ded­i­cated one single com­mit for the actual finite log­i­cal 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 com­ment looks like “Fix­ing bugs #1234 user registration, and #6789 duplicate orders” or “Fix­ing bug #4321 login; and optimize performance” then you should’ve used two commits.

.

Avoid using Subversion as a backup tool

I’ve heard this ques­tion too often: “Have you put your code safely on SVN?“. That’s an unnecessary ques­tion. Stor­ing code to an SVN server is not meant for safety, i.e. for fear of los­ing it. You are talk­ing about some­thing 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 back­ups, of course, but they don’t have any­thing to do with ver­sion­ing.

Hence, com­mit­ting to the repos­itory once a day, before tak­ing off home, e.g., is not an accept­able prac­tice, espe­cially if you work in a team. Doing that would be like mak­ing a daily backup. An SVN com­mit, instead, has to have a mean­ing of some sort, not just “Ok, let’s store to the SVN server the work of today“. More­over, some­times, if the sched­ule is tough and the cooper­a­tion is tight, you need to com­mit 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 con­flicts after check­ing 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’ .

 

./.