release

name	release
description	Cut a release — promote develop to main, generate changelog, tag a semver version, and publish release notes. Use when Project Manager marks a milestone complete and the user approves.

Release

You are the Conductor running a release cycle. The target: main now reflects the completed milestone, with a tag and a public-facing set of release notes.

Preconditions

• Active milestone marked complete by Project Manager.
• milestone-checkpoint for that milestone approved by the user.
• All target tasks merged to develop.
• CI green on develop.

If any precondition fails, abort and report which.

Workflow

1. Version Selection

• Follow SemVer based on change scope:
  • MAJOR — breaking API/behavior changes (require explicit user confirmation).
  • MINOR — new features, backward compatible.
  • PATCH — fixes only (usually via hotfix skill instead).
• Record choice in docs/ssot/decisions/adr-NNN-release-vX.Y.Z.md if non-obvious.

2. Changelog Generation

Technical Writer compiles the changelog from:

• Merged PRs since the last release tag (per Conventional Commit type).
• ADRs added in this cycle.
• Hotfixes back-merged since last release.

Write to CHANGELOG.md:

## [vX.Y.Z] — YYYY-MM-DD
### Added
- <feat entries>
### Changed
- <refactor/perf/style entries>
### Fixed
- <fix entries>
### Removed
- <entries marked BREAKING CHANGE or removing features>
### Notes
- <ADRs, migrations, operational notes>

3. Release Change Request (develop → main)

Open change request from develop to main with:

• Title: [release] vX.Y.Z
• Body: changelog entry, linked milestone, migration notes.

Reviewers:

• Senior Software Engineer — holistic code quality across all merged PRs.
• Tech Lead — architectural coherence.
• QA Engineer — every milestone success criterion verified.

Unanimous approval required.

4. Merge + Tag

atelier-check-reviews <CR> --policy unanimous
<forge> merge   # NO --delete-source-branch for release CRs
git checkout main && git pull
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

develop is not deleted — it is the ongoing integration branch.

5. Publish Release Notes

• GitHub: gh release create vX.Y.Z --notes-file <path>
• GitLab: glab release create vX.Y.Z --notes "..."
• Other forges: follow forge convention; record in docs/process/release-process.md.

6. Post-Release

• Technical Writer updates:
  • docs/roadmap/roadmap.md to mark milestone as released.
  • docs/roadmap/lessons-learned.md with release retrospective.
• Project Manager selects the next milestone's first task.
• If Fully Autonomous involvement level: announce via atelier-notify release "<summary>".

Forbidden

• Tagging main without a passing CI build.
• Force-pushing tags.
• Skipping the three-reviewer gate for release CRs.
• Partial releases that include unmerged features as "planned".

Reference Documents

• docs/process/release-process.md
• docs/process/change-review-workflow.md
• docs/process/git-flow.md
• CHANGELOG.md