Query Connector

← Back to Documentation

Query Connector Release Documentation

Releases are driven by the version field in app_version.yml. Bumping that field on main triggers automation that tags the merge commit, builds and publishes the Query Connector Docker image to GHCR, creates a GitHub Release with auto-generated notes, and posts the release link to Slack.

Semantic Versioning

Releases follow Semantic Versioning 2.0.0 with each release's version following the pattern of MAJOR.MINOR.PATCH.

  • MAJOR versions introduce breaking changes.

    A breaking change breaks backwards compatibility with previously released versions. In other words, a breaking change is something that may cause a client's implementation to stop working when upgrading from a previous version. Common examples of breaking changes include:

    • Deleting a package or public functions/methods
    • Deleting public function parameters
    • Changing a function name
    • Changing the name or order of required parameters
    • Adding new required parameters
    • Removing, restricting or changing functionality offered by a public function

    Major version releases may also include non-breaking enhancements and fixes.

    Major version releases will reset MINOR and PATCH versions to 0.

  • MINOR versions introduce new, non-breaking functionality.

    Releases with enhancements that do not break backwards compatibility require a minor version update. Common examples of non-breaking changes include:

    • Adding a package, module, or method
    • Adding optional parameters

    Minor version releases may also include fixes.

    Minor versions will reset PATCH to 0.

  • PATCH versions introduce non-breaking bug fixes.

    Releases that only contain fixes are released as patches.

Cut a release

  1. Decide the next semver version (X.Y.Z):
    • Patch (X.Y.Z+1): backwards-compatible bug fixes.
    • Minor (X.Y+1.0): backwards-compatible new functionality.
    • Major (X+1.0.0): incompatible API changes.
  2. Check with the broader team to see if there's any additional functionality someone wishes to merge into the release.
  3. Open a PR titled Release vX.Y.Z that bumps version in app_version.yml and version in package.json to X.Y.Z. Do not include a v prefix in the files; the workflow prepends it when tagging. Keep both files in sync with the same version number.
  4. Get review and merge to main.
  5. The Release workflow runs automatically on the merge commit:
    • tags the merge commit as vX.Y.Z
    • builds the Query Connector Docker image for linux/amd64
    • pushes vX.Y.Z, vX.Y, vX, and latest tags to GHCR
    • publishes a GitHub Release named vX.Y.Z with auto-generated notes
    • posts the release link to Slack (if configured)

On GHCR, the vX.Y and vX tags float to the latest release within that line; the vX.Y.Z tag is immutable.

The Release workflow does not deploy. The dev environment (https://queryconnector.dev) tracks the main image tag, which is built and pushed by the CD workflow on every merge to main (see below), so dev is already up to date by the time a release is cut. Versioned (vX.Y.Z) images are published to GHCR for downstream consumers to deploy intentionally.

Hotfix

Same flow. Open a PR that bumps the patch number (e.g. 1.0.0 to 1.0.1) and merge.

Non-release pushes

Pushes to main that do not bump the version field are handled by the CD workflow, which builds and pushes the Docker image tagged with main only. No git tag or GitHub Release is created. The CD workflow then triggers the Terraform deploy workflow, which redeploys the main image to the dev environment. This is the normal dev build and deploy flow.

Verification

After merging a release PR, confirm:

  • [ ] Actions tab: the Release workflow run on the merge commit is green.
  • [ ] Tags: git fetch --tags && git tag -l "vX.Y.Z" shows the new tag.
  • [ ] GitHub Releases: vX.Y.Z is published (not draft) with PR-list notes.
  • [ ] GHCR: query-connector has vX.Y.Z, vX.Y, vX, and latest tags pointing at this release.
  • [ ] Slack: the release-notifications channel received the release link (if configured).

Failure modes

  • Tag vX.Y.Z already exists at a different commit: the workflow fails loudly during the detect-release job. Bump to the next available version in a new PR.
  • Partial failure (tag and image created, release step failed): re-run the workflow from the Actions tab. The collision check treats a same-SHA tag as a no-op, and the GitHub Release creation falls back to fetching an existing release, so re-runs are idempotent.
  • Non-semver version: the workflow rejects pre-release suffixes (e.g. 1.0.0-rc.1). Use a strict X.Y.Z format.

Release notes

GitHub auto-generates notes from PRs merged since the previous vX.Y.Z tag. The category and exclusion rules live in .github/release.yml.

For more on customizing release notes, see GitHub's automatically generated release notes documentation.