Section 12.6. Communication

12.6. Communication

It is easy to think that Subversion is an alternative to good communication. Because it is flexible, and supportive of distributed concurrent development, it can seem at first that there is little need to discuss a project with your co-developers at the same level of detail required with no version control in place (or even a less flexible version control system). After all, you can always move things around, roll back to a previous revision, or create a new branch.

Now is the part where I'm supposed to tell you that's all wrong. That communication is just as vital with Subversion as without, and you should communicate with Subversion at exactly the same level, and in exactly the same manner, as if it weren't there. The problem is that I wouldn't be telling you the truth if I did that. Subversion doesn't require you to communicate at exactly the same level as without. It does provide you with a flexible versioning tool that allows you to drop much of the communication that was necessary in a pre-Subversion environment. In fact, a small project could probably be worked on by a group of reasonably competent developers with no communication outside of the Subversion repository, except for a brief end-project goal agreed upon prior to starting the project.

Wait, though. Before the project managers of the world band against me, or my old software engineering professor hunts me down and takes back my degree, I am not saying that you don't need to communicate if you are using Subversion. In fact, I believe that good, effective communication is vital to any software development project. What is not needed with Subversion, however, is to ignore the tool and communicate as if it didn't exist. Instead, you need to integrate Subversion into your communications policies.

12.6.1. Communicating through Subversion

Subversion is, in essence, a communications tool. At its core, it communicates the history of a software development project, of course, but it can also be used to communicate other more immediate bits of information from one developer to another. By setting policies to shape Subversion's use as a communications tool, you allow the developers working on the project to obtain the greatest possible gain in efficiency from using Subversion.

Log Messages

Good log messages are vital for good intraproject communications. As I talked about in Section 12.3.1, "Policies for Informative Logs," it is important to set policies that ensure informative log messages. Additionally, if you do regular reviews of code that has been committed to the repository, you should also have a policy of review for the logs that describe the committed changes. After a week, you will probably still be able to remember what was placed in a revision, and log messages can be edited if need be. In six months, though, a mildly uninformative log message can become incomprehensible.

Properties

Make use of properties as a communications tool. So far, I have mostly discussed properties in terms of how you can use them in automation of tasks, but they can also be an effective tool for communicating information to other developers. Log messages are good for describing meta-information about a particular revision. Properties should be used to describe meta-information about the current state of a file or directory, in order to communicate that information to other developers (and yourself, six months from now).

Some of the items of information that you might want to store as properties so they can be efficiently communicated to others include

• Testing status of the file, along with a list of known issues (or references to them in an issue-tracking system)

• Design document for the file (either the actual document or a reference to allow others to find the document)

• A TODO list for the file

• The names of the reviewers who have looked at the file, along with the date and time of the reviews

• Licensing or ownership information (especially if that information varies from file to file)

Branches and Tags

Branches and tags may not seem like an obvious means for communicating information to other developers, but if used correctly, they can be useful. Whenever you create a branch or tag, that branch or tag's existence can convey information to other developersif there is a clear policy in place for defining the circumstances for creating branches/tags, along with policy that describes their naming and organization. For example, if you use task branches, you can use the branch's location to indicate status. The project manager (or QA tester) can create task branches when scheduling the task, and place it in a /tasks/unassigned/ directory. Then, when the task is assigned and a developer begins work, the task can be moved to /tasks/in_progress/. The task branches could even be cross-referenced to an issue-tracking system by using a naming scheme that includes the issue number, or by storing an issue reference in a property.

12.6.2. Communicating about Subversion

Equally important to using Subversion to communicate is making sure that you communicate sufficiently about Subversion. When working on a software development project, it is extremely important to make sure other developers know what is going on. When you start work on a long task or create a branch, let everyone working on the project know. That way, you can avoid wasted and redundant work. You can also gain the benefit of others spotting problems before they occur. If no one knows until after the fact what you are doing, you are relying entirely on yourself to recognize potential problems, and multiple sets of eyes are always better than one.

Communication always works more smoothly if you set out clear policies for what should be communicated, and how it should be communicated (e.g., e-mail, instant message, or weekly meetings). For instance, you should have policies on communication of the following Subversion-related activities.

• A developer begins work on a particular task, regardless of whether it has been explicitly scheduled.

• A branch or tag needs to be created for a purpose other than those normally used.

• There is a need to perform a nontrivial merge in a branch used by other developers.

• A revision is (accidentally) committed that breaks previously working areas of the project.

• A bug is found in a public branch of the project.

• There is any restructuring of the repository, such as the renaming of branches or creation/deletion of publicly used directories.