Section 10.4. Product Maintenance and Development Environments

10.4. Product Maintenance and Development Environments

This section discusses how maintaining a product is helped by each part of a development environment. The next section discusses the process of deleting things such as SCM tags, files from builds, test results, and documents.

10.4.1. SCM

The different parts of an SCM tool that particularly help with maintaining an existing product are:

Change logs

Change logs will show you exactly what has changed in a given version since it was last released. They're also good for finding the right people to talk to about the changes in that version, and deciding which areas of the product ought to be retested.

ACLs

Limiting who is permitted to make changes to a release branch should mean that the amount of change to it is limited, which should in turn reduce the amount of manual retesting that is needed later on.

Annotation

The ability to know who changed each line, and in which revision, makes it easier to understand the purpose of specific changes. This is a major feature for large open source projects, where the developers may never have actually met each other.

Removing unused files

Periodic sweeps through the source code to remove files that are entirely unused is safer when SCM tools are used.

What do you do if you find you didn't add everything that you needed to reproduce a build into the SCM tool? Perhaps some patches were applied to the operating system but not noted anywhere. Perhaps the compiler used was a particular version that's no longer available? The first thing to do is add the missing requirement to your environment documents (as introduced in Section 10.1, earlier in this chapter) and keep those documents under SCM control.

The second thing to do is revisit the precise checked-out source files that were used for the build, if they are still available (see Section 9.7). Can you narrow down the effects of the unrecorded change? If you rebuild using a copy of these files and the current environment, which files are unchanged and which files are totally different? The next thing to do is find a machine that is unchanged since the time that the original build was created. Maybe the environment on that machine will give you some clues about what changed? Good luck, and remember to add the information that you do discover to your environment documents.

10.4.2. Building

After you've made changes as part of maintaining an older version of a product, automated builds for all the product's supported platforms can help to catch platform-specific errors quickly, before the changes become too distant in the collective memory of the group.

Automated builds also help to detect when changes to your development environment have broken your ability to recreate older builds. For instance, imagine that you make a change in the current version of your product and that the changed source code doesn't compile with the older version of the compiler used for a previous release. An automated build using the older environment can tell you about this explicitly, possibly even before you try to port the change back to the earlier version of the product. This gives you a clear understanding of which changes to the product make an older environment unusable.

10.4.3. Testing

Large numbers of automated unit and system tests are what most people want when they are maintaining a program. Tests for the new functionality are good, but knowing that you haven't just introduced bugs into a shipping product is even better. Of course, no test suite has 100% coverage or accuracy, so just because the automated tests pass cleanly doesn't mean you don't need to review the code changes and have other people confirm the test results and run manual tests.

The drawback of having large numbers of automated tests is that they increase the number of tests that have to be maintained. At least if you maintain the source code for the product and the tests that go with it at the same time, then the whole product gets changed at the same time. This is also a good argument for why unit tests should be built every time the product is built.

10.4.4. Bug Tracking

One of the most frustrating parts of maintaining a product is when a bug has to be fixed in multiple releases of a product. This is one place where a bug tracking system can help or hinder the maintenance effort. Sadly, tracking one bug in multiple releases is rarely done well by current bug tracking systems, as discussed in Section 7.3.3.

Even if tracking a bug in different releases is not as clear as it could be, if your bug tracking system is integrated with your SCM tool, then you may be able to tell which releases a bug has been fixed in by looking at the precise file changes that are associated with the bug.

During maintenance, assigning priorities to bugs often seems to become harderegos outside the project are now involved. On the other hand, there may be fewer bugs to deal with now that the release is in maintenance mode. Historical reports are just as useful with maintenance releases as with cutting-edge releases, especially if you can track how long it takes for bugs to get fixed. You may even be able to use this as a selling point for your product.

10.4.5. Documentation

Many different aspects of documentation need to be considered during maintenance. The original requirements documents may need to be updated if a change is not simply for a bug fix. Any major changes to the source code should be reflected in the source code's comments, especially comments that are no longer accurate after the change. The customer documentation for the product may also need to change as part of the maintenance change. Internal documentation may need to be regenerated after a change, though this is usually something done by the automation environment.

A bug that is associated with a particular change may contain text to appear in the release notes for the next release. It's helpful if all of these pieces of text can be assembled automatically from the bug tracking system into a release notes document. Many open source projects contain a file named CHANGES or ChangeLog that describes the changes made to a product in each release. There is a GNU standard for change logs as part of the coding standards at http://www.gnu.org/prep/standards/standards.html#Change-Logs.

10.4.6. People and Politics

People who write software are often neophiliacs ("lovers of the new") by nature, so getting their attention to help fix older bugs is hard. You may hear them say, "But that's already fixed in the latest version," which often implies, "You should upgrade to it and live with the possible presence of other, different bugs." Sadly, such a reply may also imply, "Fixing that bug in your version is a low priority for us because we don't make any money by fixing old versions of our software."

This tendency to neophilism can also lead to maintenance tasks being considered less prestigous within a project. To avoid this slur, some projects assign maintenance tasks to all members of the project, which makes particular sense if the original authors of the code are still present. Other long-standing projects have two teams that leapfrog over each other, with the team that maintains the oldest version of the product also developing the newest version when work on it begins.