Skip to content

RELEASING.md

Latest commit

 

History

History
158 lines (122 loc) · 6.92 KB

RELEASING.md

File metadata and controls

158 lines (122 loc) · 6.92 KB
Raw

Releasing Deft

This document describes how to cut a new Deft release.

Versioning during alpha (0.x)

Deft is pre-1.0. The project uses a loose interpretation of SemVer during alpha:

  • Minor (0.X.0) — may include breaking changes to schema, API contracts, env vars, or wire formats. Read the CHANGELOG entry before upgrading.
  • Patch (0.X.Y) — non-breaking fixes only. Safe to bump in place.

Tag format: vMAJOR.MINOR.PATCH[-channel]. During alpha the channel is preview (for example v0.3.0-preview.6). Older docs mentioned alpha / beta / rc; keep using preview unless the project explicitly changes channel. Once 1.0 ships, the channel suffix drops.

The Git tag includes the leading v. The GHCR image tag does not:

git tag     v0.3.0-preview.6
GHCR image  ghcr.io/maneek21/deft:0.3.0-preview.6

Cutting a release

1. Pre-flight

On master, confirm required check-runs are green on the latest commit (Type Check, Test API, Build, Production Image + Browser Smoke, Versioned Upgrade, CodeQL). Dependency Review runs on pull requests, not on push to master.

git checkout master
git pull --ff-only origin master

If Production Image + Browser Smoke or Versioned Upgrade is red, stop. Releases must come off a green master.

2. Open a release-prep PR

git switch -c codex/release-vX.Y.Z-channel

Edit package.json (root) to set the product version. Do not bulk-rewrite workspace package versions: packages such as @deft/app-kit have their own versioned contracts. Authoring instructions must use a package version from the same release as the host.

Set release/release-scope.json in the same prep commit. Use core for a standard Deft release with no Hermes compatibility claim. Use hermes-certified only when the tag must carry the certified Hermes integration; that scope requires the exact pinned-runtime, two-pass certificate and bundle. The workflow rejects missing or unknown scope decisions and never falls back from hermes-certified to core when certification evidence is absent.

Edit CHANGELOG.md with the actual delta from the previous tag. Keep the candidate notes under [Unreleased] and explicitly mark publication as pending. Do not carry over changes that already shipped in the previous release.

Keep public install commands pointed at the latest published image. After the release workflow succeeds and its assets are verified, make a small documentation PR to move the candidate notes into a dated version section, restore an empty [Unreleased] section, and update comparison links and installation examples. This keeps the documentation usable while release checks are running.

Commit, push, open a PR titled chore(release): vX.Y.Z-channel, wait for required CI (including Dependency Review), squash-merge.

3. Tag the release

After the prep PR lands on master and that merge commit's check-runs are green:

git checkout master
git pull --ff-only origin master
git tag -a vX.Y.Z-channel -m "Deft vX.Y.Z-channel"
git push origin vX.Y.Z-channel

Use annotated tags (-a), never lightweight tags.

4. GitHub Actions publishes the image and Release

Pushing a v* tag runs .github/workflows/release.yml. That workflow:

  • reads and validates the release scope from the tagged commit
  • for hermes-certified, provisions the exact manifest-pinned Hermes runtime and requires two consecutive clean-state employee gate passes from the release tag
  • builds and pushes the linux/amd64 GHCR image
  • publishes GitHub build provenance and keylessly signs the exact image digest
  • verifies the Cosign workflow identity and provenance before continuing
  • attaches the SPDX SBOM and corresponding source; hermes-certified releases also attach the certified Hermes integration archive and certificate
  • writes the deft.release.v2 release-manifest.json (license: AGPL-3.0-only) with the digest, signing identity, provenance type, and explicit release scope; certified manifests also record Hermes compatibility, tested runtime, and evidence digests
  • creates the GitHub Release (--generate-notes, prerelease when the version contains -)

Do not run a second gh release create. The workflow already creates the Release. If notes need a license banner or highlights, edit the Release body after the workflow finishes.

If packaging fails after the tag exists, do not move the tag. If the failed run already completed image build, provenance attestation, and signing, fix the workflow on master, dispatch it against the existing tag, and select reuse_existing_image. Recovery then verifies and packages the original tag-signed digest without rebuilding it. Do not select reuse when the original image/signature steps did not complete. If the published image itself is unusable, fix forward and cut the next preview tag.

Confirm every GitHub Release includes LICENSE, NOTICE, THIRD-PARTY-LICENSES.md, default.env.example, the source archive, SBOM, checksums, compose files, and self-hosting.md. For hermes-certified, also confirm hermes-employee-release-gate.json and the versioned Hermes integration archive are present. For core, confirm those Hermes artifacts and all hermes_* manifest claims are absent. Confirm the image label org.opencontainers.image.licenses=AGPL-3.0-only (the production Dockerfile sets this; release.yml passes VCS_REF and SOURCE_URL). For a certified release, verify the Hermes certificate reports the exact tag commit and two clean-state passes, then compare its certificate and bundle digests with release-manifest.json and SHA256SUMS. Run the digest-first Cosign and gh attestation verify commands in docs/self-hosting.md against the published manifest. If signing, signature verification, provenance publication, or provenance verification fails, the workflow must stop before the GitHub Release is created.

Hotfix releases

For an urgent fix on a previously released minor version:

  1. Branch off the released tag: git switch -c hotfix/vX.Y.Z+1 vX.Y.Z-channel
  2. Cherry-pick or land the fix.
  3. Bump the patch number, update CHANGELOG.md, tag vX.Y.Z+1-channel.
  4. Push the tag and let release.yml package it.
  5. Open a PR to merge the hotfix branch back into master so the fix isn't lost when the next minor goes out.

License and source artifacts

Every current-line release is licensed under GNU AGPL v3.0 only. Historical tags through v0.2.0-preview.4 retain BSL 1.1 as shipped. Do not rewrite those tags. GitHub's source archive plus the repository's build and installation scripts are the Corresponding Source offered with the official image.

Documentation gate

Complete the documentation release checks before publication. Keep the website and README on the same recommended installation path, and record install, restore, upgrade, MCP, and Module evidence for the release.