Continuous releasability
We practice continuous releasability. This is a variant of continuous delivery adapted to a monthly release cadence that serves the needs of customers running their own Sourcegraph instances.
Continuous Releasability Contract
main
branch is always releasable- Every new feature includes a feature flag
main
is always releasable
Every change merged into main
must preserve the releasability of main
. Releasable means
that the revision can be released to customers. In particular,
- Up-to-date changelog and docs: The changelog and documentation reflect the current feature set.
- Docs must be updated as soon as a feature is merged and enabled.
- You can merge a feature without yet updating the docs if it is behind a disabled feature flag.
- QA: Every feature has been QA’d by an appropriate set of users in an appropriate environment.
- Simple bug fixes should be tested at the very least by the author.
- Simple features should be tested by someone other than the author.
- Complex or scale-sensitive changes should be tested by multiple people on one of the dogfood instances.
- No regressions: The regression test suite passes.
- The regression test suite is not run in CI, because it is time-consuming and somewhat flaky.
- The author should manually run the regression test suite before merging, unless they are certain the change does not break the regression test suite AND introduces no new behavior.
- Up-to-date Regression test suite: Every key workflow has a regression test.
- This means adding/updating regression tests when you add/update workflows.
What to do if the main
branch builds are failing and it is not in a releasable state?
A feature flag is required for every new feature
The preferred feature flag mechanism is the
experimentalFeatures
field of site config.
Feature flags achieve 2 things:
- They allow us to maintain the Continuous Releasability Contract while still merging big features
into
main
(disabled behind the feature flag) before they are fully tested. This is useful if a feature needs to be deployed to a dogfood instance or beta-tested before being deemed release-ready. - They give us a quick mechanism to disable features if a feature inadvertently breaks the Releasability Contract. E.g., if we discover a critical bug in a new feature 1 day before release, we can immediately disable it to make the release deadline.
Exceptions
In some cases, it may be prohibitively expensive to preserve releasability. For example, a major
change made the indexed search backend horizontally scalable. Maintaining strict releasability of
main
would have required spinning up the new backend alongside the old one with a feature flag
to toggle between the old and new backends. It was far easier to switch over and fix any bugs
immediately after.
Such cases are exceptional and the conditions under which they are allowable will change as the team and codebase grows. If maintaining the Continuous Releasability Contract is too expensive for a given feature, notify the Release Captain and together come up with a QA and rollout plan. Try to minimize the period of time during which the Releasability Contract is broken. Here are some rules of thumb:
- Do as much QA and testing as possible before merging into
main
. - Have a plan for quickly testing and fixing any issues that arise immediately after merging into
main
. - Make the change as much in advance of the release date as possible.