Best Practices for Software Version Control

This post contains some of the best practices for using version control systems in your project (for ease of reference, I shall refer to it as SVN). As a software developer, you will almost definitely used one of the variants of version control systems (e.g. JDeveloper's SVN plugin, TortoiseSVN..), thus good version control practices are as important as good programming practices. The recommendations listed in this wiki are by no means exhaustive, but the principles should easily transfer to other systems as well.

Here are 3 tips:

1. Commit often and in logical chunks

The basic work cycle is always update your working copy before doing any changes to files. By doing “update to head”, resolve any conflicts, run a build and make sure there are no failures before checking in code. In general, it is preferred to commit changes in logical chunks. This means that changes that belong together should be committed together, changes that don't shouldn't.

If many code changes are done to a project at the same time, split them up in to logical parts and commit them in multiple sessions. This makes it much easier to track the history of individual changes, which will save time when trying to find and fix bugs or doing code reviews.

2. Write meaningful commit comments

Although often under-utilised, comments should be brief but detailed enough to describe what was changed. If several changes were made, write one line or sentence about each part. If the list of changes gets too long, consider splitting the commit into smaller parts. Otherwise, it can be problematic when code commits are not fine-grained, e.g. submit a week's worth of changes to multiple modules in a large pile. Thus, comments can be very useful to distinguish trivial from non-trivial changes in the repository.

Prefix your comments with Identifiers

Prefixing commit comments with identifiers is a good way to indicate the type of change made. It also allows easier filtering of content later when we do code reviews.

Identifier	Indication
FIX	Issue fixes / Improvements
ADD	Change Requests / New files
REMOVE	Delete files
TEST	Add/remove logs for debugging purposes
DOCS	Documentation only changes e.g. code comment
STYLE	Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)

Reference the Bug ID

If the change is about fixing a specific bug, do reference the bug number in the commit message (assuming your project has some sort of bug tracking database or system).

3. Do all file operations in SVN

Whenever there is a need to copy, delete, move or rename files or folders in the repository, do so using the corresponding file operations in the version control system. If this is done only on the local file system, the history of those changes will be lost forever.

Conclusion

Consider giving the above suggestions a try, you might like it. Please share your thoughts and feel free to add on to the list of best practices too. If you are interested in more practices on working with SVN, this is a recommended book:

Version Control with Subversion, by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato