BEP 6: Branching Strategy

BEP 6	Branching and Releases
Authors	Mateusz Paprocki, Bryan Van de Ven
Status	Implemented
Discussion	https://github.com/bokeh/bokeh/issues/10177

This document defines the process for how branches and releases are handled.

Definitions

Base Branch

branch-x.y A permanent branch for a release level that is the basis for releases, e.g branch-2.2

Major Release

x.0.0 Infrequent, irregular releases with major changes, including breaking changes, e.g 3.0.0

Minor Release

x.y.0 Regular releases every 4-6 weeks, with new features and bugfixes, but no breaking changes, e.g 2.2.0

Patch Release

x.y.z Ad-hoc releases for high-priority bug fixes, e.g 2.2.1

Release Branch

release-x.y.z A temporary branch created to collect final release updates, e.g. release-2.2.1

Release Level

x.y The version up to minor release, e.g. 2.2

Process

Regular Bokeh development proceeds according to a series of minor x.y.0 releases, nominally targeted to occur every 8-10 weeks. Infrequent major x.0.0 releases occur whenever it is necessary to introduce large or breaking changes.

Active development towards the next minor release occurs on a branch-x.y base branch. For example, if the next minor release is for version 2.2, then normal development will be against the branch-2.2 branch. The current base branch will be configured as the default branch for the repository, so that new Pull Requests automatically default to submitting against it. Force-pushes are not allowed to base branches.

Immediately after a minor release, a new base branch will be created for the next minor release, and it will be configured as the new default branch.

Patch releases do not represent continued development. Patch releases generally only occur in the following situations:

• When it an important bug fix cannot wait for the next minor release to occur.
• When some extenuating concern mandates that an older line of development receive some specific critical update.

It is preferable that changes first land on the current base branch, and then specific work to include in a new patch release be back-ported to the older base branch (updating any issue or PR milestones as necessary). The suggested process is to cherry-pick commits to a single new PR against the older base branch. However, if changes are only relevant to an older line of development they may be made directly against older base branches.

The main branch records an archive of releases, with the HEAD of the main branch typically corresponding to the latest version released. No active development should occur on the main branch, and normally no commits should land directly on the main branch (exceptions may happen for things like CI or other infrastructure configuration).

Retiring branches

In order to keep the number of active branches open at any one time to a reasonable level, and to clearly signal that old branches are permanently closed to future changes, old development branches will be periodically deleted, and replaced with a placeholder commit. Specifically, the following branches shall be kept at any point in time:

• the base branch from the most recent previous release level
• optionally, the base branch from the next most recent previous release level
• any number of current/future base branches (usually this is just one, but may occasionally be more)

Upon retiring, the last commit of a branch shall be tagged with branch-x.y-final-commit.

Revisions

Changes to this document shall be recorded below:

Date	Change
2020-10-08	Implemented
2020-10-15	Remove copy-paste error under "Revisions"
2023-11-04	Add policy for retiring old branches