Visit djangoplay.org ↗
gitaiflow / Runbooks / Release Runbook
DocsgitaiflowRunbooksRelease Runbook

Release Runbook

gitaiflow follows Semantic Versioning. The current package metadata (pyproject.toml) declares:

2 min readApplies to v1.1.3
On this page ▾
  1. Versioning
  2. Rollback
  1. Confirm the working tree is clean.
  2. Update [project].version in pyproject.toml.
  3. Update CHANGELOG.md (or generate the entry with gitaiflow --changelog --since <last-release-date> --path .).
  4. Run linting: make lint.
  5. Run tests: make test.
  6. Run the deterministic regression suites (core service layer and telemetry consent — internal-only, not published here).
  7. Build all four platform binaries: make build-all (the macOS leg must run on real Apple Silicon hardware).
  8. Verify architecture headers: file installers/* (see expected output in ../deployment/binary-distribution.md#5-verify-artifact-architecture-headers).
  9. Generate RELEASE_NOTES.md from the CHANGELOG.md entry for this version (gitaiflow --release-notes), then create and push the annotated release tag — either directly (git tag -a vX.Y.Z -m "...", git push origin vX.Y.Z) or via scripts/release/tag_release.sh, which also creates the GitLab/GitHub releases from RELEASE_NOTES.md and links the built binaries.
  10. Publish: make release (uploads every binary in installers/vX.Y.Z/ to the GitLab Generic Package Registry as both the versioned and latest assets, then regenerates the R2 manifest — including installers/latest.txt — and syncs to Cloudflare R2) — or make all to chain test → build-all → release in one command.
  11. Install the published version in a clean environment (curl -fsSL https://install.djangoplay.org/gitaiflow | bash -s -- vX.Y.Z).
  12. Verify gitaiflow --version and gitaiflow --help.
  13. Run the full platform verification matrix — macOS, Linux amd64/arm64 containers, Windows PowerShell — from ../deployment/binary-distribution.md#section-d-verification--integration-testing.
  14. Run a real functional smoke test against a configured AI provider (gitaiflow --path . --change-summary) to confirm the compiled binary's bundled dependencies (httpx, certifi, and — on Windows — the prompts/templates data files) came through the compile intact.
  15. Spot-check telemetry consent behavior post-release (gitaiflow --telemetry status) — see the telemetry consent test suite (internal-only) Part 2 for the full sequence.

Versioning

text
version = "1.1.0"
requires-python = ">=3.11"

Rollback

Because both the one-line installers and the Generic Package Registry latest pointer are overwritten in place on each successful release, there is no separate "rollback" action beyond re-running registry_update.sh with a previous version's installers/ directory if a bad release has already reached users:

bash
git checkout vX.Y.Z-1 -- installers/  # or rebuild that tag with make build-all
GITLAB_TOKEN=<token> ./scripts/release/registry_update.sh latest

If a release step fails mid-way, registry_update.sh is safe to re-run once the underlying issue is fixed — package-registry uploads and the R2 sync (which uses --checksum) are both idempotent.