Codeline Policy
Main Line , Task Branch , and Release Line all follow different rules and have different stability requirements. The pattern describes how to use and enforce rules for working with a given codeline to keep your ecosystem active.
Similar Structure, Different Purpose
A codeline is a branch, and branches are structurally the same. What differentiates one codeline from another is how you work with it and identify it. Working on a different kind of codeline requires a context shift, and you want to minimize cognitive overhead.
Documentation can add overhead, but relying on undocumented shared understanding may not scale well as new team members grow. Documented rules need to be kept up to date with changing needs, so you need a way to identify when rules should change and a mechanism for updating them promptly.
One way of encouraging consistent compliance with rules is automation. Automation, like rules, may not cover all scenarios, so any automation needs to be flexible.
The rules for a codeline need to be clear, easy for developers to follow, and adaptable.
Define the Rules in Context
For every codeline, define a Codeline Policy to help developers decide what process to follow before integrating code changes from another work stream to the codeline. Use automation to reduce cognitive overhead.
A Codeline Policy should include:
The naming convention for the branch.
The purpose of the branch.
Required steps to push changes to the branch.
Lifetime and disposition.
The rules can be as detailed or simple as the team needs, and requirements can be enforced by convention, tooling, or automation.
A common approach is to document the rules either in a README in the code repository or in a document on a team Wiki and then add automation to your build system and CI pipeline.
Some examples
Here are some examples of how the code line policies might vary between branches. Adapt rules that make sense for your team
For the Main Line:
Name: main
Purpose: to be the central integration point for all work
Prerequisites:
All Tests Pass
CI Pipeline stages pass
Peer review
Lifetime: Continues
Disposition: N/A
For a Task Branch:
Name: something that describes the task:
If you use an issue system: issue-123myFeature
A Free form Description: myFeature
Purpose: To work on a task
Prerequisites:
All Tests Pass on a developer machine
Lifetime: Until a task is complete, it should typically not be more than one day
Disposition: Deleted after merge
For a Release Line:
Name: contains the following elements:
“release-:
Version id
Date
Purpose: To track released code
Prerequisites:
For changes from the Main Line:
A basic integration test has passed
For hotfix changes:
CI Pipeline checks pass
An integration test passes
Lifetime: Until you no longer need to track a release
Disposition: Can be kept around for historical purposes or deleted when a version is no longer deployed
Each of these criteria can be enforced by hand or by tools. For example, you can create a task branch:
on the command line
git checkout -b task-123with a makefile target
through an issue-tracking system that has SCM integration
The important thing is that it’s straightforward to know what the branch is for.
Cautions
Useful policies are brief, automated, or both. Don’t spend too much energy on documentation. Or overthinking the policy.
Any rules are likely to have exceptions you didn’t consider, so — especially for automated gates in the CI pipeline — allow for overrides. For example, you may have a test coverage check, which is a good proxy for ‘did you right a test’ but in some cases, a reduction in coverage is acceptable, Or there may be cases when skipping a Code Review makes sense.
Next Steps
Many of the requirement style elements of a Codeline Policy can be done with Automated Checks.
To Get Started
You probably already have some conventions that you use for branches. This pattern suggests simply that you:
Capture the key elements of the policies in a document
Automate the more technical steps (build script, CI System etc) as you go
Keep it simple.