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 CD workflow runs on the merge commit. It builds the Query Connector Docker image for linux/amd64, pushes it to GHCR with the main, vX.Y.Z, vX.Y, vX, and latest tags, and deploys that exact image digest to https://connector.dibbs.tools.
  6. Once CD succeeds, the Release workflow:
    • tags the merge commit as vX.Y.Z
    • 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.

Because Release only runs after a successful CD run, a release is never published for an image that failed to build or deploy. 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 and deploys it to https://connector.dibbs.tools. No git tag or GitHub Release is created. This is the normal build and deploy flow.

Redeploying a specific version

Run the CD workflow manually (Actions, CD, "Run workflow") with the version input set to an existing GHCR tag such as v1.2.3 or main. The workflow skips the build and deploys that tag's image digest. See terraform/azure/README.md for how the deployment is structured.

Verification

After merging a release PR, confirm:

  • [ ] Actions tab: the CD run on the merge commit is green and the Release run it triggered is green.
  • [ ] Demo: https://connector.dibbs.tools serves the new version.
  • [ ] 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 Release workflow fails loudly at the tagging step. Bump to the next available version in a new PR.
  • CD failed (build or deploy): no tag or release is created. Fix forward on main; the release is published when CD next succeeds on a commit whose version differs from its parent, so a follow-up fix commit will not retroactively publish the release. Re-run the failed CD run instead.
  • 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.