Skip to content

Latest commit

 

History

History
187 lines (119 loc) · 6.61 KB

RELEASING.md

File metadata and controls

187 lines (119 loc) · 6.61 KB
Raw

Releasing

Overview

This repo contains three types of release artifacts:

  • Go Binaries for Terraform Engine, Policy Generator, and Terraform Importer (tag: vX.Y.Z).
  • Templates for the Terraform Engine ("templates" for short) (tag: templates-vX.Y.Z)
  • Policy templates for the Policy Generator ("policies" for short) (tag: policies-vX.Y.Z).

These three groups of artifacts are not coupled with each other, so they are released separately.

Versioning

Releases are tagged with Git Annotated Tags following semantic versioning (semver). All binaries are versioned together as one unit, and so are all templates and all policies.

Rules:

  • v1.x.x - MAJOR version, increments on breaking changes.
  • v1.2.x - MINOR version, increments on backwards-compatible new features.
  • v1.2.3 - PATCH version, increments on backwards-compatible bug fixes.

Examples of potential breaking changes:

  • The Engine drops support for .yaml config files.
  • A CFT module module MAJOR version bump (i.e. terraform-google-kubernetes-engine).
  • A Terraform provider MAJOR version bump.
  • Terraform itself has a major version update and drops a feature we relied on, causing us to heavily modify the templates.

The 0 Version

The only exception to the above is the 0.x.x version. As described in semver, this version is for initial development; anything may change at any time, and the public API should not be considered stable. During this time, we will bump the 0.MINOR version for breaking changes, and the 0.x.PATCH version for all other changes.

Release Branching

For now, we do not preemptively create release branches. Release tags are made on master by Repo Owners, and we primarily work on the latest version of the binaries, templates and policies.

Release branches may be cut from old releases as necessary, but we would generally encourage using or migrating to the latest versions of everything.

Frequency

We release an unstable version after each commit via an automated release flow. This release may include breaking changes. We may make versioned releases any time as needed. The MAJOR/MINOR/PATCH versions are updated as needed.

Caveat about versions

Solutions docs and guides should pin the versions of the binaries, templates and policies to ensure that users will see consistent binary behaviour and output files.

However, as cloud APIs and other infrastructure change over time, in practice solutions may stop working even with the same versions as before. We cannot guarantee indefinite compatibility, and encourage solutions and guide writers to periodically check for correctness and consider updating to use the latest versions.

Automated releases

Automated releases are configured to trigger on tag pushes, via GitHub Actions. See the workflows.

To trigger an automated release:

  1. Choose a version. It should match the regex ^v[0-9]+\.[0-9]+\.[0-9]+$. That is, a leading "v", followed by three period-separated numbers.

    version="fill"

  2. Create the Git tag.

    For binaries:

    git tag -a "${version}" -m "Binaries ${version}"

    For templates:

    git tag -a "templates-${version}" -m "Templates ${version}"

    For policies:

    git tag -a "policies-${version}" -m "Policies ${version}"

  3. Push the tag:

    git push origin --tags

  4. Follow the workflow on the Actions page.

  5. Binaries releases will also auto-generate a simple changelog from the commits made since the previous tag. Look at the new release in GitHub and edit this changelog if required, as some PRs are not important and including them in the notes adds clutter and can confuse users.

Manual releases

If automation is not available, releases can be made manually. Follow the steps above to create and push a tag, then manually build and upload the release artifacts as described below.

Binaries

  1. Build the binaries:

    ./build/build-binaries.sh -v "${version}"

    This will create binaries for each tool for each supported OS and ARCH.

  2. Go to the releases page.

  3. Create a release from the ${version} tag and upload all the tfengine_*, policygen_* and tfimport_* binaries as assets.

  4. Generate a changelog:

    ./build/changelog_binaries.sh

  5. Edit this changelog if required, as some PRs are not important and including them in the notes adds clutter and can confuse users.

  6. Add the changelog to the release description.

Templates

  1. Bundle the templates:

    ./build/build-templates.sh -v "${version}"

    This will create a .tar.gz bundle for the Terraform Engine templates.

  2. Go to the releases page.

  3. Create a release from the templates-${version} tag and upload the templates_${version}.tar.gz file as an asset.

Policies

  1. Bundle the policies:

    ./build/build-policies.sh -v "${version}"

    This will create a .tar.gz bundle for the Policy Generator policies.

  2. Go to the releases page.

  3. Create a release from the policies-${version} tag and upload the policies_${version}.tar.gz file as an asset.

Using Hub to create a release instead of the GitHub UI

You can use the hub command instead of the GitHub UI for creating releases. Follow instructions to install it, then run one of the following commands:

  1. For binaries:

    hub release create $(printf -- ' --attach=%s' ./*-amd64) -m "Binaries release version ${version}" -m "$(./build/changelog_binaries.sh)" "${version}"

  2. For templates:

    hub release create $(printf -- ' --attach=%s' ./templates*.tar.gz) -m "Terraform Engine templates release version ${version}" "${version}"

  3. For policies:

    hub release create $(printf -- ' --attach=%s' ./policies*.tar.gz) -m "Policy Generator policies release version ${version}" "${version}"