Photo by John Collier. Library of Congress, Prints & Photographs Division, FSA-OWI Collection, Reproduction Number: LC-USF34-084002-C.

Louise Thompson, daughter of a newspaper editor in Richwood. She is a printer's devil. Richwood, West Virginia, September 1942.

When you have multiple codelines, developers need to know how to treat each one. A Release Line (17) might have strict rules for how and when to check things in, but an Active Development Line (5) might have less strict rules. This pattern describes how to establish the rules for each codeline to suit its purpose.

Note

How do the developers know which codeline to check their code in to, when to check it in, and what tests to run before check-in?

Each codeline has a different purpose; one codeline might be intended for fixing bugs in a particular release; another codeline might be used for porting existing code to another platform; yet another is for day-to-day development. These codelines have different requirements for stability. If code is checked in to a codeline, ignoring the rules, productivity will suffer. Developers need to know which codeline they should be using and what the policies are on that codeline.

You can identify different codelines by their names. A codeline's name can tell you something about its purpose, but it can't express all the finer points of codeline usage, such as the policies. For example, a release line can be very restricted or only slightly slow, depending on the organization's strategy and vision. And it can be hard to come up with good, unambiguous naming conventions. Figure 12-1 shows how we might diagram the association between a codeline and a policy.

Figure 12-1. Each codeline needs different rules.

Once you decide how stable a codeline needs to be and how to realize that level of stability through processes, you need to inform developers of these policies and then enforce them. You can provide formal documentation describing the finer points of codeline usage, but this requires extra effort for documentation and maintenance; once the documentation becomes out of sync with the policy, it is useless. Also, developers may perceive the formality of such a document as overbearing or as if it were some draconian tactic to interfere with “real work.” It is easier for people to use a policy they understand and believe in than one that seems arbitrary (Karten 1994).

You want developers to behave properly and follow the policy, but even well-intentioned people forget things in the heat of a deadline. You can use peer pressure or punishment to enforce policies, but that can break down the team.

You can use automation to enforce policies, but it is hard to implement automated procedures correctly. Sometimes some steps in a process do not make sense, and it is hard to encode policies that allow you to skip a step. If you do provide a mechanism for sidetracking parts of the process, developers may ignore the process, from a well-intentioned sense of experience if nothing else.

For a codeline, different roles might have different degrees of leeway with executing the processes. For example, you may want to forbid permanently deleting a file's history on a release line, but at times it makes sense, such as when someone checks in a new file accidentally. Someone needs to be able to fix this, or you will end up with useless files in your codeline. If you are too restrictive with permissions, you need to be able to give people permissions they need quickly. For example, if only the Director of Development can perform certain operations, but the Director also travels much, you may be stuck. You may not be able to have an open codeline in all cases without having a free-for-all.

Define the Rules of the Road

Note

For each branch or codeline, formulate a policy that determines how and when developers should make changes. The policy should be concise and auditable.

The codeline policy explicitly states the rudimentary policies an organization has about how to conduct concurrent development and how to manage releases. Vance says that “a codeline policy defines the rules governing the use of a codeline or branch” (Vance 1998). In addition to using naming conventions and meaningful codeline names, formulate a coherent purpose for each codeline. Describe the purpose in a clear and concise policy. The policy should be brief and should spell out the “rules of the road” for the codeline, including

• The kind of work encapsulated by the codeline, such as development, maintenance, or a specific release, function, or subsystem

• How and when elements should be checked in, checked out, branched, and merged

• Access restrictions for various individuals, roles, and groups

• Import/export relationships: the names of those codelines it expects to receive changes from and those codelines it needs to propagate changes to

• The duration of work or conditions for retiring the codeline

• The expected activity load and frequency of integration

Make the policy short and to the point: A good rule of thumb is one to three paragraphs, with one page as an absolute maximum.

Keep in mind that not all codeline policies require all the previous information. Specify only what is essential. Some version control tools allow you to associate a comment with each branch and codeline name. This is an ideal place to store the description of a suitably brief codeline policy. Developers can run a branch description for the codeline instead of digging around for its documentation. Otherwise, store the codeline policy in a well-known, readily accessible place. You could perhaps provide a simple command or macro that will quickly display the policy for a given codeline name.

You should create a branch whenever you have an incompatible policy.

Some example of codeline policies follow.

• Development codeline—interim code changes may be checked in; affected components must be buildable (Wingerd and Seiwald 1998).

• Release codeline—software must build and pass regression tests before check-in; check-ins are limited to bug fixes; no new features or functionality may be checked in; after check-in, the branch is frozen until the entire QA cycle is completed (Wingerd and Seiwald 1998).

• Mainline—all components must compile and link, and pass regression tests; completed, tested new features may be checked in (Wingerd and Seiwald 1998).

Enforce parts of the policy by using any mechanism that your version control tool supports, such as triggers. If automatic enforcement becomes too constraining, use automation to report on adherence to the policy.