Communicate With Version Control

June 9, 2011

Chapter 10 – Written Communication

Version control is an often-overlooked avenue for the exchange of ideas. The metadata stored in a version control system — comments, diffs, and change logs — presents an accurate representation of your coding effort. The bug tracking system is where you talk about your product and the version control system is where you talk about your code.

The purpose of a version control comment is the place to talk about the changes you made to the code and why you made them. Taking the time to put valuable information into version control comments will make the version control system an excellent reporting tool for your team, as well as increasing your visibility.

Version Control As a Reporting Tool

Version control is a single place where you can see all the changes the team has made to the code over a fixed period of time. All version control systems have reporting tools which can show you the logs of what has changed. These logs differ a little bit between one product and another, but they all have the following information about each change: when it was made, who made it, what files they changed, and the comment they made. The information in these logs flows in two directions. The log will help you see what your team is doing, and it will help your team (and your manager) see what you are doing.

Encourage your team to write descriptive check-in comments by setting a good example and showing them how useful this information can be. There is no better tool for getting a good understanding of the code changes that are being made.

Check in often

Checking in your code is how you share it with the rest of your team. Part of sharing information proactively is checking in often. A good general guide is to check in as soon as your code won’t block other people. This should be multiple times every day. Checking in often not only shares your code with your team, but it gives you a good history of your work.

In order to accommodate this style of checking in you should strongly encourage your team to work with branches. Version control branches are a way of separating the code you are working on from the code everyone else is working on. A standard use of branches is to quarantine a product just about to be released. Most products go into a code freeze at the end of the release cycle and branches allow you to keep working during this time.

Previous post:

Next post: