Codeline Policy

A pattern to describe how to work on a codeline

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-123

• with 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.