10 Best Practices for Version Control

Used correctly, version control is an invaluable tool – but following some basic guidelines can help you get even more out of your version control system. In this post, we share ten best practices for getting the most out of version control.

1) Version control everything…..

Version control is no longer just for source code management. Thanks to user-friendly and intuitive tools such as TortoiseSVN and uberSVN, version control is increasingly becoming a tool for programmers and non-programmers alike. Consider encouraging every member of your team (including the non-techies) to keep all files and folders related to your project under version control. This could include meeting minutes and whiteboard notes, architectural designs and user documentation. Even for documents that are unlikely to change, it’s useful to have everything in one place and available to everyone on the team.

2) …but don’t treat version control as a backup system

Although version control does provide you with a backup of your files and folders on a remote server, using your version control like a backup system is a bad habit that doesn’t make the most of the system’s unique functionality (although it is possible to backup your Apache Subversion repositories.)

3) Commit easily readable documents

If you’re committing documents that require formatting before they can be read, consider committing them in a more accessible form, such as a PDF. In addition to making documents quicker and easier to access, this allows you to refer people directly to a document in the repository. However, remember to update both versions of the document when you make changes (or better yet, automate this process.)

4) Be consistent with your file/folder names

Implementing a logical naming convention will make it easier to locate particular items. Ideally, this naming convention should be explained in a coding conventions file, which is accessible to all members of your team, and this convention should extend to all the projects in your repository.

5) Commit little and often

Commit small changes frequently, instead of committing many small changes bundled into one large chunk. This will reduce the chances of encountering complications such as merge conflicts, and will reduce the complexity of such conflicts when they do occur.

6) Only commit finished work

Never commit half-completed code. This seems to go against the concept of ‘commit little and often,’ but the solution is to split the task you’re working on into manageable but logical pieces, and then commit these regularly.

7) Update regularly

This ties into the concept of ‘commit little and often.’ Perform regular updates on your working copy, to keep up to date with the changes being made in the trunk. This is important, even if it seems your current work has little to do with the rest of the team. It is also good practice to update your working copy before making any changes.

8 ) Make use of log messages

Always make use of log messages, and make sure you include as much information as possible (what changes were made, why, and by whom, etc.) If the commit deals with a specific bug or change request, include the issue or bug number in the log message.

9) Implement a sane project layout

Maintaining a version control system can become a complex task, so implementing a logical project layout from the beginning is crucial. Some version control systems, such as Apache Subversion, don’t impose a strict project or repository structure, which makes planning your layout in advance even more important.

10) Test, test, test

Get into the habit of systematically testing everything, especially before you perform a commit or a merge. Also consider CI and assertion testing on feature branches, which is a useful way to indicate code maturity and progress.

1 Response to “10 Best Practices for Version Control”

  • This is a great list. I especially like that it encourages other best practices such as consistent naming conventions which are often overlooked by novice developers.

Leave a Reply