release

Disciplined Releases

Use this workflow whenever creating or preparing a release. Act like a release engineer: optimize for correctness, traceability, safety, production readiness, and repository hygiene over speed.

Release model

• Releases promote completed, validated work from develop to main.
• main represents production-ready code only.
• develop remains the integration branch for completed development work.
• Releases must not include incomplete, unrelated, experimental, or ambiguous changes.
• Prefer an explicit release/<version> branch for traceability.
• Do not merge directly from develop to main unless the repository explicitly requires it.
• The process must be explicit, auditable, and reversible where possible.

Available helpers

• scripts/validate.py validates release branch names, SemVer versions, release branch bases, merge directions, and tag names.
• references/checklist.md contains the required gates, release PR template, release notes outline, and post-release summary format. Read it before starting release work.

Non-negotiable safety rules

• Always inspect git status --short before release operations.
• Never release from a dirty working tree.
• Never discard, overwrite, or hide user changes.
• Never use git reset --hard, git clean, git restore, git checkout --, force push, forced branch deletion, tag deletion, tag overwrite, or --no-verify.
• Avoid globs, wildcards, recursive operations, and broad pathspecs unless strictly necessary.
• Use explicit branch names, explicit tags, and explicit files.
• Do not automatically resolve conflicts by guessing.
• Stop if sensitive or unsafe content is detected.
• Stop if release scope cannot be confidently determined.

Required pre-release inspection

Run narrow, explicit inspection commands before starting:

git status --short
git branch --show-current
git rev-parse --verify develop
git rev-parse --verify main
gh auth status

Then inspect the release scope with explicit branch names:

git log --oneline main..develop
git diff --stat main..develop
git diff --name-status main..develop

Verify:

• current branch and working tree state
• develop exists and is the intended source branch
• main exists and is the intended production branch
• develop contains only completed, intended release work
• commits and diffs between main and develop are understood
• breaking changes, migrations, dependency updates, config changes, and operational risks are identified

If unrelated, incomplete, unsafe, or ambiguous changes are detected, stop and report the issue.

Versioning

Determine the release version using SemVer unless the project clearly uses another scheme:

• Patch: backward-compatible bug fixes.
• Minor: backward-compatible features.
• Major: breaking changes.

Do not guess the version if release impact is ambiguous. Ask for clarification or document the ambiguity as a blocker.

Validate the version and branch name:

python3 scripts/release.py version 1.4.0
python3 scripts/release.py branch release/1.4.0
python3 scripts/release.py base release/1.4.0 develop

Ensure version bumps are consistent across all relevant files. Do not create inconsistent or partial version updates.

Release branch rules

• Create release branches from develop.
• Use release/<version>, for example release/1.4.0.
• Do not use vague release branches such as release/latest or release/final.
• Release branches are for stabilization only.

Allowed release-branch changes:

• version bumps
• changelog updates
• release notes
• documentation corrections
• metadata updates
• release-blocking bug fixes

Disallowed release-branch changes:

• new features
• unrelated refactors
• opportunistic cleanup
• incomplete or experimental work

Changelog and release notes

Update changelog or release notes if the project uses them. Do not invent changes that are not supported by the inspected diff or commit history.

Summarize user-visible changes clearly. Group changes by category where useful:

• Features
• Fixes
• Breaking changes
• Performance
• Documentation
• Internal changes

Include migration notes when required and rollback considerations when useful.

Validation

Run available project validation before promoting to main:

• tests
• linting
• type checks
• formatting checks
• build checks
• release checks
• Lefthook or other hooks

Treat validation failures as hard blockers. Do not bypass checks or hooks. If validation tooling is absent, perform internal checks where possible and document what was checked.

Release PRs

If the repository uses PRs, create a release PR from release/<version> into main:

gh pr create --base main --head release/1.4.0 \
  --title "chore(release): prepare 1.4.0" \
  --body-file /path/to/release-pr.md

The release PR must clearly state:

• release version
• summary of changes
• validation performed
• risks
• migrations or breaking changes
• rollback considerations

Do not create a release PR with unrelated changes. Do not merge a release PR unless checks pass and approval requirements are satisfied.

Merge flow

Only merge after validation passes.

Required sequence:

1. Verify source and target branches before every merge.

2. Verify the working tree is clean.

3. Validate merge direction:

   python3 scripts/validate.py merge release/1.4.0 main
   python3 scripts/validate.py merge release/1.4.0 develop
   

4. Merge release/<version> into main.

5. If release-specific changes were made, merge release/<version> back into develop.

6. Stop on conflicts and report conflicted files and required decisions.

7. Ensure develop and main do not diverge unintentionally.

Tagging

Create a release tag only after main contains the released changes.

• Use the project's existing tag format when detectable.
• Common formats: v1.4.0 or 1.4.0.
• Do not invent a new tag format if one already exists.
• Tags must point to the release commit on main.
• Do not move, delete, overwrite, or force-push tags.
• Prefer annotated tags when the project uses them.

Validate tags before creating them:

python3 scripts/validate.py tag v1.4.0 1.4.0

Post-release verification

After release completion, verify:

• main contains the release commit
• the release tag points to the correct commit on main
• release-specific changes are reflected back into develop
• no unintended divergence remains between main and develop

Summarize the release using the template in references/checklist.md.