Photo by Alfred T. Palmer. Library of Congress, Prints & Photographs Division, FSA-OWI Collection, Reproduction Number LC-USE6-D-000162.
Proud of his job. Smiling worker in an eastern arsenal hand finishes the interior surface of a cradle for an eight-inch gun, railway carriage. 1942.
An Integration Build (9) is easier to debug if you know what went into it. This pattern discusses how to balance the needs for stability, speed, and atomicity.
Note
How much work should you do between submissions to the version control system? How long should you wait before checking files in?
When you make changes to the code base, you want to focus on the act of coding. Administrative tasks, such as checking in changes, precheck-in testing, and so on, are a distraction. Coding is a sequence of changes, bug fixes, and enhancements, and you need to track these changes. The revision history in your version control tool should reflect the way file changes map to functionality changes.
To add one feature or to fix one defect, you may need to make changes across many parts of the code base. But every change introduces a potential instability in the mainline. You would like to be able to roll back or remove a change if it causes unexpected problems. For this to work, changes need to be consistent and complete.
Depending on your Codeline Policy (12), a check-in may involve a long sequence of steps, including testing, that will take time. You may want to avoid this overhead and delay checking in a change for as long as possible. For multiple feature changes that require changes to more than one module, it is certainly easier to make all the changes to a module at once. But the longer you are working on your own copy of the module, the more likely you may be in conflict with other people's changes, and the harder it will be to roll back a particular change.
When an integration build breaks, you want to be able to track down the change that broke it. A long list of changes in an integration build report is more work to process, but a more detailed change history makes it possible to remove selectively changes that may have broken the build.
It can be tricky to decide what a task-oriented change really is. Sometimes the definition of a task is natural. You may be fixing a problem that was assigned an issue number. If the issue can be fixed by changing one file, you have a natural atomic check-in. If a change spans multiple components across various systems, it is not obvious what changes go together unless they are checked in. If you err on the side of smaller units of work per check-in, you gain the overhead of processing the check-in. If you err on the side of larger-grained units of work, you lose the ability to back out small changes.
You want to be able to maintain a stable codeline and associate changes with features or defects that were fixed.
Strive to have each commit of code changes reflect one task. This will enable you to make the most important changes first. The unit of work can be a new feature (or part), a problem report, or a refactoring task.
It is OK to batch changes if it makes sense and batching does not add significantly to the time that you are working on a local copy of the code. Consider the complexity of the task, how many files or components you need to change to implement the task, and how significantly the change will affect the system (how risky it is). Each change should represent a consistent state of the system.
Examples of reasonable change tasks are
A problem report (a broad problem may have two or more check-ins associated with it)
Changing calls to a deprecated method to use a new API for an entire system
Changing calls to a deprecated method for a coherent part of the system
A consistent set of changes that you accomplished in a day
When in doubt, err on the side of more check-ins because it is easier to roll back changes and see the effects of integration with other people's work. Also, because your revision control system is an indicator of the “pulse” of the development work, strive to check in changes at least once a day, if it makes sense.
Sometimes it makes sense to have a check-in for multiple defect reports or features. A degenerate example of this is a one- or two-line section of code that was responsible for numerous problem reports. In this circumstance, multiple check-ins would not be possible. But whenever you are changing separate parts of the code base, do one check-in per feature or defect report.
A precheck-in policy that is too vigorous can discourage this practice, so consider ways to streamline the precheck-in validation to test only what is necessary. Extended code freezes make it difficult to maintain this practice. Extended code freezes are bad for many reasons because they interrupt the flow of work.
Before you check in, be sure to catch up your workspace to the current state of the codeline and test for compatibilities.
Some changes are far-reaching and inherently disruptive and long-lived. In this case, consider using a Task Branch (19). If multiple people are working on a task branch, perform small-grained commits on the task branch.
Unit Tests, Smoke Tests, and Regression Tests, as well as the Edit Policy, provide guidance on how to encourage small-grained check-ins.
Good integration between the development environment and the version control system will make the commit process fit in better with the flow of the developers' work.