12.3. Log Data It's easy to write bad log messages. I've seen it done countless times (and, I must admit, have done it a few times myself). After long hours of coding, it's easy to top it off with "Added a bunch of stuff," "Fixed all the compile errors," or even "Fixed an off-by-one error." It is so easy, in fact, that despite all levels of experience or good intentions, you're almost certain to get a few similar log messages in your repository at some point. You'll rue their entry, though, the day you need to search out the exact point where a feature was added or a bug was fixed. With poor log messages, you find yourself frantically searching through diffs and guessing dates in order to pinpoint an exact revision amidst a sea of commits, instead of being able to do a quick search through the log messages. In general, the more detailed your log messages, the more useful they'll be in the future. As a rule of thumb, every log message should be detailed enough that you would want to decipher exactly what changed for the project in that revision 10 years from now. By that point, you will have completely forgotten all context for the commit, and will not likely remember any information that is left out of the log. One way to help jog your memory and ensure that you don't forget to include a description of every modification in the log is to use svn diff to review the changes made before performing the commit. The best way to ensure good log messages from everyone involved in a project is to develop a clear set of policies for what should (and should not) go into a log message. If the expectations for log messages are clear, it is much harder for individual developers to slack off and say, "This revision doesn't matter. I'll just dash off a quick message and move on to something else." Additionally, if you have a clear format for log messages, searching through them to find a particular piece of information will be much easier. In some cases, you may even find that rigid log formats help with scripts that parse the logs to add automated functionality. 12.3.1. Policies for Informative Logs The most important consideration for log messages is to make them informative. Log messages that don't tell you anything are like comments in code that just restate the obvioususeless. Good log messages inform the reader as to what the revision adds to the project and why the revision was needed. To help you generate an overall policy that draws useful log messages from your project's developers, here are some of the specific policies that you should consider. If developers have what is essentially a checklist of points to include in their logs, useful log messages will quickly become second nature. State the specific issue solved by this revision. Explain, in as much detail as you need, exactly what functionality has been added to the project or what bug has been fixed. If the revision is in response to an issue in an issue-tracking system, you should reference the issue with an issue number or URL (or other reference, as appropriate). If there are any other external documents that describe the issue, you should also make reference to them, with enough information for a later developer to find the appropriate documentation. Briefly explain why the issue needed solving. With the exception of Easter eggs, features are rarely added to a project for no reason. You should include a brief description of why a change was made in your log messages. This is especially important for future reference. Two or three years down the road, some other developer may be searching through the log messages, trying to fix a bug or add a new feature, and if he doesn't know why your revision was put in, he may accidentally remove it without fully understanding the consequences. List any known side effects. If you know of any side effects caused by your revision, you should make sure they are explicitly enumerated, because they will likely not be obvious to the next person to work around the revision. As with the description of why, this helps avoid many long hours of debugging obscure changes far (or not so far) in the future. Listing known side effects is also important for other developers currently working on the project, so that they know what they can expect from updating their working copy to include your revision. List any interface changes. Knowing what changed in the interface is important for other developers working concurrently on the project, by helping to inform them of potential changes that need to be made to the sections of the project that they are responsible for. They can also act as an important tool for future developers tracking the project's history. By being able to clearly see points where interfaces changed, it is also easier for developers to identify modifications that need to be made to code that is reused from older revisions. Explain what, if anything, was removed. If the revision removes any functionality from the project, it is important to explicitly list it. Even if the functionality removed seems minor and inconsequential to the rest of the project, other parts of the project may depend on it. If that dependent functionality breaks as a result of the revision, it will be much easier for the developers responsible for fixing it to find the problem if they are able to clearly see that something was removed when they look at the logs. Reference other relevant revisions or tags. For instance, if the revision you are committing builds on a previous revision, you should mention that revision and how they are related. This makes it easier for future developers to trace the history of the project when they are making a modification. It is easy for the many interdependencies in a project to get lost after a relatively short period of time (especially if the original developers leave), so this little bit of extra information can greatly reduce the risks of future modifications to the project. Include any Subversion commands that are part of the revision. When you perform an svn merge, Subversion doesn't explicitly record everything that went into the merge. Similarly, svn copy and svn move can be difficult to trace effectively. You can make these commands much easier to track by explicitly referencing their use in your log messages. This is especially important for merges, because future merges can end up working incorrectly if you don't know the merge history of the directories involved. Don't be afraid of humor in log messages. As long as humorous log messages are not offensive, and don't detract from the information being conveyed, developers should be encouraged to occasionally have fun with log entries. Not only does this give developers a good outlet for their creativity, but it helps to encourage developers to write good log messages (and gives them an incentive to pay attention to the log messages that others write).
12.3.2. Parseable Log Messages Creating automated tools that can make use of log messages is very powerful. The problem is making the tool understand what the log messages are saying. If log messages are completely free-form, this can be impossible to do with any accuracy. It can also be difficult to use hook scripts to validate log messages that don't contain any predefined structure. Therefore, if you want to use scripts that look at your log messages, you will be well-served to develop a log message structure that every log message should conform to. Use section tags to explicitly partition the log message. If you have specific points that you want made in your log messages (such as purpose, description, and an issue tracker reference), it may be useful to begin each point with a well-known tag. For example, you might format your log messages like the following example. ISSUE: 1758 PURPOSE: Fixes the bug that was causing a crash when the program was closed. DESCRIPTION: Removes an incorrect reference in the Window class destructor that was accessing m_mybutton after it was destroyed.
This way, you can easily search for the revision where issue #1758 was fixed, or check the log message on commit to ensure that the purpose and description have been filled in. Define strict formats for external references. Whenever a log message references an external source, such as an issue-tracking system or design document, you should have a well-defined format for making that reference. For instance, you could reference an issue-tracking system with a format such as [ISSUE:##]. In the following log message, the explicit reference would allow a script to find the issue referenced. Fully implemented the requirements in [ISSUE:453].
If a log message references changes to an interface in the project, you should be able to parse that information in a script to identify exactly which interfaces were changed. That way, you could write a script that would automatically identify interface changes and send warnings to the appropriate developers, or even perform an analysis on the project and identify places where modifications need to be made. The following interface change section from a log file shows how you might structure those changes. INTERFACE_CHANGES: ADDED int Button::on_clicked(int btn) TO button.h CHANGED void Button::on_mouseover(void) IN button.h TO int Button::on_mouseover(void) REMOVED void Button::destroy(void) FROM button.h
Define a standard set of terms and keywords for your project. Developers should use explicitly defined common terminology when talking about common project details. That way, searching becomes a more useful tool for examining the project's history. Additionally, scripts can be written that discern meaning from log messages by looking for certain terms and phrases.
12.3.3. What Not to Include Log messages should be detailed, but there is such a thing as too much information in the logs. If each log message is a novel unto itself, no one will be able to glean anything useful from a quick read-through. Therefore, to help keep things short without sacrificing utility, there are some things you shouldn't include in your log messages. Don't use source code from the revision in your log messages. If developers need to see the actual source code changes, they can use svn diff to obtain that information. If you need to reference the actual code that was modified, use references to the source code itself (don't use line numbers, as those will quickly end up out of date). Don't list the files that were changed. Subversion already gives you the ability to see what files have changed by using the svn log -verbose command, so this information is redundant. Avoid going into too much detail for things described elsewhere. In general, it is better to give a brief description of what you are referencing, and let the user go to the referenced material if she needs more detail.
|
