Change control

Contents

See also:

Overview

 Consider the following scenario.

Frank, an enthusiastic software developer (aren't we all?), writes a fabulous piece of foobar code. He tests it, installs it in the public repository, and then keeps working on other code that uses foobar. A few weeks later, Ernest starts using Frank's foobar code, and discovers that it has some design flaws that weren't apparent to Frank. Ernest, in the spirit of fixing problems when they're found, adds some code and moves some other code around to fix the flaws, and keeps on working.

A few days later, Frank is suddenly very unhappy. Firstly, his build broke because of a couple of small changes Ernest made to the types of a couple of methods. Easily fixed. Then he discovers that he is going to have to rework a lot of his code because Ernest redesigned part of the internal architecture of the foobar, which showed up in the order of method calling and the way event callbacks were handled. Eventually, the whole system is functioning again, but not without some acrimonious email debate, code rework, and perhaps some damage to the team dynamics.

How could this have been done better? Ernest could have tried to work around the flaw -- but ultimately that's a negative impact on quality, and Ernest clearly felt that it was unacceptable. Or a change control "committee" could be established to evaluate the impact and cost/benefit of changes such as Ernest's. OK, but that's only half the story -- the other half is that a peer review could have solved the problem before it occured. Firstly, Ernest (and others) could have voiced their concern about the design flaw at a time when fixing it would be relatively cheap. Either the flaw a) would have been fixed, or b) it wouldn't have been fixed, but the reasons for not fixing it would be documented and -- more importantly -- accepted by other developers as a necessary decision in light of other constraints.

The rest of this page outlines a simple framework for combining these two aspects: quality improvement by peer review and change control by improved visibility. It was written to help manage change in small teams. Other than the (perceived) cost of performing design and code reviews, it is very cheap. (In fact, it's so simple, I am almost embarrassed to write about it.)

The purpose of the framework is to improve the way that you manage change. It is not to prevent change or creativity, since change is an essential part of the process of software development. Ultimately, the framework is about confidence in quality, and commitment to stability.

It is written with Java in mind, and so emphasizes packages, but it can probably be applied without much difficulty in other languages. For more substantial reading (and references) on the reasons for reviews and change control see Steve McConnell's books Code Complete or Software Project Survival Guide.

Rating levels

The most visible part of the framework is a rating that is assigned to each package or class. The rating levels are red, yellow, green, or blue. The basic idea is that a package or class starts at red, and advances up to blue by a light-weight review process. At each step in the process, the package or class author proposes an increase in its rating; the chief reviewer for that package is then responsible for organizing a review, and advancing the ranking after the issues raised in the review have been resolved.

Generally, it's easier to rate whole packages. This makes management easier and provides a form of "micro-milestone" that aids completion. Sometimes, an individual class will need to have a different rating than the rest of the package it's in, and this is fine -- just annotate the source file appropriately.

The meanings of the four rating levels are:

Red
The package is preliminary.

This means that we have no confidence in the design or implementation (if there is one) of this package, and that anyone that uses it can expect it to change substantially and without notice.

Yellow
The package has passed design review.

This means that we have a reasonable degree of confidence in the architecture and design of the package, and that it will not change in any substantial way. We do expect the API to shift around a little during the coding process. You can code to this API with the understanding that updates will be needed as the API settles.

Green
The package has passed code review.

This means that we have high confidence in the correctness and stability of the API to this package, and that we have reasonable confidence that there are no major bugs in the implementation. The implementation may not yet by complete and there may be performance work needed but it's usable by "early-access" developers.

Blue
The package has passed final review, and will remain backwards-compatible.

This means that are confident that the code is of sufficient quality for public release, and that we have made a final committment to maintain backwards-compatibility. In order to make this commitment, we have what we consider to be a complete test suite, we have stress-tested the package by using the API in other code, and we have conducted a final review of all relevant materials (source, documentation, demos, etc).

That's it. Following sections outline a process for using the rating, how to deal with change, and other things to consider.

A suggested process

 The process suggested here is simple and easy to remember. For each level except red:
  1. The author announces the package ready for review;
  2. The review moderator organizes and moderates the review;
  3. The author responds to the issues raised in the review, redesigning or reworking as necessary;
  4. The review moderator signs off on the changes, and announces the new package rating.
Piece of cake! I believe that, as a general rule, the process works better if the author initiates reviews, as the commitment to passing the review will be higher. It is important that not too much time pass between the review and the rework, or the author will lose motivation and the (hastily taken) review notes will start to lose meaning.

Depending on the project, you may choose to implement specific requirements for passing a review. Here are some guidelines that apply to packages.

Yellow
If a subsystem or package is being reviewed, then the review requires detailed design and API documentation, including OMT or UML diagrams and explanatory text. If one or a few classes with well-defined or obvious roles are being reviewed, then an API specification or javadoc output is fine.
Green
Green is a fairly large jump from yellow. Since a rating of green means that other developers are going to rely on your code, passing green requires a test suite that is substantial enough to give the reviewers confidence that the code really does what it says it does.

In general, code that relies on other code that is not itself reen should be taken green only with appropriate noting of the dependency and the need to fix it. For example, if package A uses package B and B is still Red, then make B at least Yellow before making A Green. The same priniciple applies to inheritance hierarchies: a class that inherits from a Red class cannot be reasonably made Green, since you can't have any confidence in its stability.

Blue
Blue means that the code has been stress-tested in use by other packages. This requirement improves the chances that a package really does fulfil its requirements, at least as far as its clients are concerned. One way to encourage this (suggested by John Davis) is to require that at least one client package be Green before making a package Blue.
Don't forget that the ratings apply only to individual packages. Complete system integration and testing is out of the scope of this guideline.

Managing change

 Change is a fundamental aspect of software development. Without going into details of why you might need to make changes, here are some guidelines as to how to approach making them. If the guidelines for change at each level cannot be met, then take the package back to a lower level. This is an action that is acceptable and in some cases probably inevitable -- but it is a very strong signal that the changes need to be evaluated very carefully, since the package has reached its current level by a careful (hopefully!) review process.

This section outlines the changes allowed by each rating level. If a change greater than that allowed is required, then the package must be dropped back a level. The first step in doing so is to stop and consider if it really is required. This is not a simple yes-no question, as it depends on an analysis of the impact of the changes and probable benefits. In Code Complete, Steve McConnell suggest a "change committee" be established -- doing so may be a little heavy for a small team, but the spirit is the same: have someone else (other than the proposer) evaluate the change to see if it really is worth it. If it is, great -- do it. At least you will know it's worth the pain!

There is one overriding rule for any changes at all: code checked into the public repository must not break the build. Source code changes that break the build check-point disrupt all work and are unacceptable.

Red
Changes are expected. If you know that other code already uses red code (if you have any), then you should at least notify whoever is responsible for that other code. Demos and test suites might be examples of code that depends on red code. But other than that, any changes to red specifications or code are acceptable (with the exception noted above!).

Yellow
Minor changes to the interface of a yellow package are expected and acceptable. Major changes -- for example, reworking the collaboration of some of the classes in the package -- are things that "should" have been detected in the design review before the package went yellow, and thus require a re-review. (If this can't be done immediately, take the package back to red.) In any case, major changes to a yellow package are to be considered with some care -- since the package has already been reviewed, then you need good reason to make very substantial changes.

Change in the implementation code of a yellow package is expected as part of the development process.

Green
Changes to the interface of a green package are to be considered very carefully. A substantial amount of code may already depend on this interface, and adding new methods is better than changing old ones if it can be done without destroying the conceptual integrity of the package.

Changes to the implementation of green packages are normal and expected, provided that the semantics behind the interface do not change. If they do, then take care to ensure that code that depends on this package will not break, or are updated.

Blue
The interface to a blue package must not change in an incompatible way. Changes that extend the existing interface without changing its semantics are acceptable, but these changes should themselves be reviewed in a yellow-green-blue sequence. Implementation code can change, but this should be done only for bug fixes or for planned performance enhancements. Any but the simplest fixes should be reviewed again to maintain confidence in the package.

A blue package cannot be taken back to a lower level, as doing so would break the commitment to backward compatibility implied by blue.

There are other ways with dealing with change at more fundamental levels. Firstly, designing a system with possible or probable change in mind will make it easier to accommodate large-scale changes with minimal disruption to existing packages. Consider implementing wrappers, facades, adapters, or (even) subclasses to deal with change instead of making major modifications to code that has been thoroughly reviewed and tested. Remember that a blue package represents a substantial investment in intellectual effort, not to mention sweat.

Adapting the method

The rating levels and process outlined above are guidelines only. Modifications can and should be made to account for different development styles, the purpose and importance of a package, and other circumstances. Ultimately, the best guideline to give is that the reviewers use their judgment in applying these guidelines. These guidelines, I believe, will be most effective if you think "confidence and commitment," not "rules and regulations."

Documentation
A package that is undocumented is hard to use. My personal inclination is to encourage a reasonable level of documentation by i) expecting a reasonably complete design specification to go to yellow, ii) expecting substantial embedded documentation (for extraction by javadoc) to go to green, and iii) requiring complete embedded documentation and a programmer's guide derived from the specification to go to blue.

Specification
Any specification form that is understandable and maintainable should be accepted to go to yellow. I prefer not to use documentation generated from source code as the "specification" as that will change as the source changes and is hard to recover later.

Object models, in OMT or UML, should be required for any design review.

More levels
The four levels described here may seem too "far apart" in some circumstances. In particular, the gap from yellow to green is quite large, and may take quite a while to cross whlie the code is in a state where others need to depend on it but don't have the "confidence" given by a green rating. Consider introducing sub-levels, such as "green-alpha" and "green-beta."

Retrospective application
Sometimes it may be necessary to consider rating code that is already considered "done." In this situation, there is little point in going back and starting from red -- instead, the reviewers must judge whether a single code review or final review is sufficient for a green or blue rating. The key points to remember are confidence and commitment: whatever rating you are giving the package, you need to have the same confidence in and commitment to it as if it had gone through the entire process.

Individual files
It is often not possible to rate a whole package at once, either because of its size or because some parts of it are poorly-understood (simply because that's the nature of software development). In the first case, it is easy enough to break it into parts and have multiple review meetings. In the second, you should perhaps consider if the less-well-understood part of the package can be isolated into a cohesive sub-package -- this sub-package can then be reviewed and rated independently from the main package.

In any case, it is perfectly acceptable to rate a package overall but note exceptions in the package status document.



Last updated: %G%