Project Syn Tools Release Process

Releases often just require a new SemVer tag with v-prefix to be pushed, for example v1.2.3.

Commodore Components

Commodore Components are to be tagged with SemVer with v<major>.<minor>.<patch>[-rc<rc>] pattern (optionally includes Release candidates tagging).

Example 1. Version examples

  • v1.0.0

  • v1.2.3-rc1

Generally, we discourage the use of v0.x versions. Instead, we recommend that developers directly release v1.0.0 after the initial implementation is complete. If a prerelease version is required, developers can use a release candidate suffix (for example -rc1).

The release process itself is straightforward:

  1. Identify which type of pull requests were merged since last release (fixes, enhancements or breaking changes) to decide on the next SemVer version number. See also Review Guide for the pull request label usage.

  2. Create and push a new Git tag on the default branch.

  3. If there are no breaking changes since the last release, immediately bump the version number of the released component in the Commodore defaults repository.

How to deal with breaking changes

There’s two broad categories of breaking changes:

  1. Breaking changes which can be automatically rolled out with appropriate upgrade jobs in the component. In those cases, the component has implemented a automatic upgrade path where no user interaction is required.

  2. Breaking changes which require changes in the config hierarchy. This case requires that users bump the version along with the config changes that are documented in the upgrade documentation.

For Project Syn setups that use common or global defaults in their hierarchy, bumping the version in the defaults can usually only be done once all clusters have been upgraded to the new version.

Lieutenant API and Operator

All Project Syn Tools that require the container image tag to be in sync with the release, require additional preparation:

  1. Create a release branch

    git checkout -b prepare-release

  2. Edit deploy/kustomization.yaml to point to the to-be-released version

    1. On Lieutenant API also update the Steward tag in deploy/deployment.yaml: Environment variable STEWARD_IMAGE.

  3. Commit and push the changes and create a Pull Request

    git commit -a -m "Prepare release vX.Y.Z"
git push -u

  4. Check and update Getting Started guide and Tutorial: Writing your First Commodore Component (These guides need to be up-to-date and work 100% all the time)

Additional work for major releases

If a "major" release is being done, the following additional work needs to be done:

  • Update the Roadmap

  • Write a blogpost and spread it on social media

  • Close the associated GitHub project and internal Jira project (if applicable)