Sourcegraph releases

Release Schedule

As of April 2024, Sourcegraph releases features monthly (see RFC 864) The 2024 schedule is as follows (version numbers are subject to change):

These releases may require manual migration steps.

Releases are the responsibility of the Release Team, and are performed by the team.

Releases are published with semantic versioning syntax, though Sourcegraph releases do not necessarily follow the versioning semantics. The patch version can be between 0-65535 with the number always increasing.

Selecting Release Dates

The following are general guidelines for selecting release dates:

• Day 5: Monthly release

• Day 20: Patch release

We chose day 5 to avoid holidays and other events at the beginning of the month, such as new quarterly review meetings and discussions. However, on some occassions these days fall on Friday or the weekend, so we generally consider the following criteria in the event the schedule above fall on a Friday or the weekend:

1. Pick the next working day that isn’t a Friday. This gives time for release prep.

Patch releases

Generally speaking patches will only include bug fixes for previously released features. In some occasions we may release improvements to address issues that may not technically a bug fix, and in some occasions we may backport features provided they are:

1. Behind a feature flag
2. Low risk and well tested (with flag on and flag off)

Release captain

The release captain is responsible for managing the release process and ensuring release is executed successfully. The release captain may delegate work to other teammates, but such delegation does not absolve the release captain of their responsibility to ensure that delegated work gets done.

The release captain should create a tracking issue using the release issue template at the beginning of the release cycle.

Release captain responsibilities are currently owned by the Release Team.

Release tooling

sg is the tool used to create releases.

Release branches

The release process uses a release branching model. Monthly releases are created from the main branch and are usually contained in a long lived release branch (e.g 5.3.270, 6.2.205). Individual releases associated with the monthly release are tagged from these release branches.

To avoid confusion between tags and branches:

• Tags are always the full semantic version with a leading v (e.g. v5.3.207)
• Branches are always the dot-separated major/minor/patch versions with no leading v (e.g. 5.3.207).

A---B---C---D---E---F---G---H---I---J---K---L (main branch)
     \                       \
      \                       `---v5.3.427 (5.3.427 monthly release branch)
       \
        `---v5.3.207---D'---v5.3.405 patch release (5.3.207 monthly release branch)

Issues

This section documents how do we deal with issues that are found during the release process.

CHANGELOG.md

When releasing a new version, the Release Captain may need to manually update the CHANGELOG.md. Follow the instruction below:

• Check past entries in CHANGELOG.md to understand the changelog format.
• Create a new H2 title named {major}.{minor}.{patch} (the new version) after the Unreleased section if it doesn’t already exist.
• Copy all changelog entries of the commits belong to this patch release into the new H2 title ## {major}.{minor}.{patch}, grouped into the types they were originally in (e.g. ### Added, ### Changed, ### Fixed, ### Removed).

Cody clients and backwards compatibility

Cody client extensions, such as the VS Code extension, need to maintain backwards compatibility with Sourcegraph servers back to 5.0.0. The Sourcegraph server has no backward compatibility requirements with respect to the clients. However, the server should try to maintain backwards compatibility with clients on a best effort basis.

Why only back to 5.0 instead of our standard policy of latest version and previous major version? That will eventually be our policy. However, since Cody was new to 5.0.0, it’s a necessary exception to that policy.