Sourcegraph releases

Release Schedule

As of March 2023, Sourcegraph releases features quarterly (see RFC 770) The 2023-2024 schedule is follows (version numbers are subject to change):

These releases may require manual migration steps.

Patch releases

A patch release refers to a patch version increase of Sourcegraph (e.g. 3.0.0 -> 3.0.1).

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 guild.

Release tooling

The Sourcegraph release tool is used to generate releases as associated materials (such as tracking issues). It leverages the following issue templates, which list all individual steps that needs to be performed, for each type of release:

• Release issue template
• Patch release issue template

Release branches

Each major and minor release of Sourcegraph has a long lived release branch (e.g. 3.0, 3.1). Individual releases are tagged from these release branches (e.g. v3.0.0-rc.1, v3.0.0, v3.0.1-rc.1, and v3.0.1 would be tagged from the 3.0 release branch).

To avoid confusion between tags and branches:

• Tags are always the full semantic version with a leading v (e.g. v2.10.0)
• Branches are always the dot-separated major/minor versions with no leading v (e.g. 2.10).

Development always happens on main and changes are cherry-picked onto release branch as necessary with the approval of the release captain.

A---B---C---D---E---F---G---H---I---J---K---L (main branch)
     \                       \
      \                       `---v3.1.0-rc.1---I'---v3.1.0---J'---v3.1.2 (3.1 release branch)
       \
        `---v3.0.0-rc.1---D'---v3.0.0---F'---v3.0.1---J'---v3.0.2 (3.0 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.

1) Start a minor release

Major and minor releases are released on a fixed schedule, see when we release.

2) Minor release tracking issue

The tracking issue for the current minor release is created as a part of the post-release step from the previous minor release. Learn more from the release issue template.

The Release Captain should review and follow the instruction in the release tracking release for the next steps. At a high level, it includes the following steps:

• Build a release candidate and verify CI passes
• Publish final images
• Update documentation
• Update references of the image tag to the new version using batch change

3) Wrapping up

Follow the instruction from post-release in the release tracking issue to wrap up the release and schedule the next minor release.

1) Kickstart a patch release using the Sourcegraph release tool

CE or the products team will start requesting a patch release by submitting a patch release request. Learn more from the patch release issue template.

Upon the Delivery team or the Release Captain receives the patch release request and we have decided to roll out a new patch release, the Release Captain should follow the instruction in the patch release request issue to kickstart the patch release process. The instruction is located at the bottom of the patch release request.

2) Patch release tracking issue

The Sourcegraph release tool creates a patch release tracking issue which contains a list of action items the Release Captain has to perform. Learn more from the patch release issue template.

The Release Captain should review and follow the instruction in the patch release tracking release for the next steps. At a high level, it includes the following steps:

• Build a release candidate and verify CI passes
• Publish final images
• Update documentation and changelog
• Update references of the image tag to the new version using batch change

3) Revisit patch request issue

Now it’s a good time to go back to the original patch release request and close it.