Skip to content

Release Process

Denise Yu edited this page Nov 4, 2019 · 6 revisions

The Release page shows each repository that has unreleased changes.

Each repository on the release page has the following information:

  • The next milestone for the repository (as determined by sorting the milestone names).
  • All pull requests and issues within that milestone.
  • The number of commits that have been merged since the last commit that was tagged as a GitHub release.
  • All pull requests associated to the above commits. This way we don't have to remember to put them in milestones; all merged PRs are accounted for automatically.

When viewing an individual repo, e.g. concourse/concourse repo, all issues and pull requests are broken down into the following tabs:

  • To Do - open pull requests and issues in the milestone. These must be completed prior to releasing.
  • Done - merged pull requests and closed issues that have not yet been documented.
  • release/documented label - done PRs/issues that have been documented and added to the release notes.
  • release/undocumented label - done PRs/issues that we have decided not to document.
  • release/no-impact label - done PRs/issues that have no impact on the release (e.g. CI-only PRs or issues that were introduced but then fixed prior to shipping).

The goal of the release view is to burn through all issues/PRs in the "Done" column by adding the appropriate release/* label. Once the "To Do" and "Done" tabs are empty, we are ready to ship!

Where to coordinate & communicate

All release coordination is to be done in the #contributors channel on Discord. Be sure to join it!

Shipping core resource types

Core resource types must be shipped prior to shipping a Concourse version, as they are currently bundled into the core distribution.

For each core resource type listed (if any), assess their listed changes to determine if the release should be a major, minor, or patch release according to semver. After making your decision, trigger the appropriate job in the resource's pipeline:

After each core resource types ships, it will automatically feed into the main Concourse pipeline. This will produce a new Concourse release candidate that must make its way through the pipeline.

Shipping Concourse

Once all of the core resource types have been shipped, the next step is to ship Concourse itself.

Bumping the version

Concourse follows the following versioning scheme, again based on semver:

  • A major bump must be done for backwards-incompatible changes, as per semver.
    • The scope of "backwards-incompatible" is limited to core Concourse functionality, i.e. pipeline definitions. Renaming flags or otherwise changing how Concourse is deployed does not necessarily constitute a major version bump.
  • A major bump may be done for a release that has substantial new features, primarily ones that we think everyone should notice.
  • A minor version bump must be done when there are new features that are backwards-compatible.
  • A patch version bump must be done when the only changes are bug-fixes.

Based on the content of the release, determine what type of version bump the release warrants, and trigger one of the following jobs:

Note: there is no patch job - this is the responsibility of release pipelines which are scoped to their minor version.

Unlike the semver jobs in the resource pipelines, these jobs only bump the version - they don't ship Concourse. After the version has been bumped the rc job must run to actually create a candidate version to build build and test. This can take some time, so the semver jobs should be triggered as soon as we know what the next version will be - not when we're just about to ship.

Writing documentation and release notes

Once the version number is decided, create a GitHub milestone for it if there isn't one already, and add any issues or PRs to the milestone that we want to make sure to release.

At some point, the "To Do" tab should be empty, and we can move on to the "Done" tab.

For each issue or PR on this tab, the first question to ask is "does this have any impact on users?" - if it doesn't, for example because it's a PR that just changed ci/ stuff, or if it fixes a bug that was never released in the first place, apply the release/no-impact label. This will move it to the release/no-impact tab where it can be simply ignored.

For the remaining issues/PRs in the "Done" tab, it's time to write release notes and update the documentation. Once both are done, apply the release/documented label. This will move it to the release/documented tab.

Alternatively, if the issue or PR has user impact but is incredibly boring and not worth noting (this should be infrequent), you can apply the release/undocumented label. This way we at least know what things we didn't document.

All documentation and release notes are written using the Booklit content authoring system. You may want to consult its documentation for syntax and the base functionality.

Additional functions are provided by the concourse-docs plugin - for example, \ghuser{foo} for referencing a GitHub user, \ghissue{123} and \ghpr{124} for referencing issues and PRs, \ghrelease{v5.0.0} for referencing a GitHub release, and \resource{s3} for linking to a resource repo. These are all commonly used in release notes.

Updating the documentation

Documentation lives in the concourse/docs repo.

Changes should be made to a branch corresponding to the version with the patch portion excluded - e.g. v5.2.

Some features may involve writing a lot of documentation. Feel free to ping @vito on these issues - we try to have a consistent voice and style throughout the documentation, which can be difficult with a rotating cast.

You may also want to create a pull request for the branch if you want someone to review the changes.

Writing release notes

Release notes are kept in the concourse/release-notes repo. Each version has a corresponding file under lit/(version).lit. These files are used to render GitHub-flavored Markdown documents which reference the documentation.

Release notes should be written on master; there is no branching strategy for this repo.

The structure for a given release note .lit file is as follows:


  Breaking changes go first.

  Super impactful features come second.

  Super impactful fixes come third.

  Minor features come fourth.

  Minor fixes come last.

Release notes can and should reference sections of the documentation by using \reference{some-tag}. When the Markdown content is generated, these will link to the referenced section at

Areas for Improvement

  • Each release branch technically is a fork of the ci/ configuration. This means CI changes made to master are typically not reflected in the release branches and vice versa. This can get pretty confusing if e.g. refactoring is done on a release branch and not brought back to master.
    • Is there anything we can do about this? This may be desireable in some situations (e.g. an older release has a different/older build process), but it has resulted in a lot of uncomfortable manual reconciliation between branches. Maybe it's just the maintenance tax we pay for supporting old versions?
    • Can we extract the tasks and scripts in ci/ into a separate repo that feeds directly into all pipelines? That way we could at least ensure the tasks are consistent, and any release-specific changes would be only in the pipeline configuration. If we need a different version of a task config for a certain release or branch we could just duplicate it under a new name (e.g. concourse-build-5.1.x.yml).
  • We currently have a lot of duplication between the main concourse pipeline and each release pipeline. This is further exacerbated by the introduction of branch pipelines.
    • Can we extract the building and testing parts into a general, semver-free 'branch pipeline' which can be applied to master, release/*, and all feature branches?
    • ...and then have some way to just take the 'good' artifacts that came out of this pipeline and ship it? We'd have to re-build the fly and concourse assets with the version number baked in. Can we trust that our builds are reproducible?
    • Can we normalize 'drills' as part of this branch pipeline?
  • Can we have a process for beta/pre-releases?
  • Each release note should link its PR. We should have a script or something to make this easier.
  • Pull requests should be auto-added to the appropriate milestone as their release/* labels are applied.
  • Pushing the docs shouldn't be part of the release pipelines. A docs pipeline should auto-deploy anything pushed to master of concourse/docs to Documentation changes should be made to branches named after the minor version (e.g. v5.2). New minor versions and/or patches for current minor versions should be merged into master once the version is shipped.

Release Anchor Responsibilities

  • If you're unsure about what is going into this release and/or what minor line it should be part of, check with Scott, Alex, and track anchors!
  • Create a milestone if it doesn't exist:
  • Tag all PRs that are going into the release with the milestone
  • Release notes: Make sure all PRs are documented with a release note, and corresponding Concourse docs if it's user-facing. Grab those release notes and consolidate them into a new file with the release version, e.g. release-note/ Be aware that a release note might have already been written by whoever merged the PR in release-notes/ Cadet's release page also contains a helpful overview of everything that's been tagged so far by the team.
  • Find or create a release branch in the format release/{minor line}, e.g. release/5.7.x. Patch releases don't get their own branch.
  • When all PRs have passed automated tests and merged into master, compose a new PR containing only the commits that should land in the release branch. Open a PR to merge those changes into the release branch.
  • Do some pipeline stuff to publish the actual release....
You can’t perform that action at this time.