Skip to content

docs: clarify release execution phases#41

Merged
debop merged 1 commit into
mainfrom
docs/release-docs-clarity
May 24, 2026
Merged

docs: clarify release execution phases#41
debop merged 1 commit into
mainfrom
docs/release-docs-clarity

Conversation

@debop
Copy link
Copy Markdown
Contributor

@debop debop commented May 24, 2026

Summary

  • Add a release flow map to the central release runbook so operators can see each phase, version state, required evidence, and next action.
  • Add version and internal-reference state tables to the canonical Version Management Policy.
  • Clarify that the pre-release checklist is for release-prep branches, while develop should normally use matching internal -SNAPSHOT references.
  • Fix the post-release checklist to describe reopen PRs as baseVersion advancement plus empty snapshotVersion, not checked-in *-SNAPSHOT version bumps.
  • Add a lesson capturing the phase-gate documentation rule.

Verification

  • git diff --check

Reduce release confusion by making phase boundaries, version states, and post-release reopen work explicit in the central release docs.

Constraint: release docs must preserve the canonical Version Management Policy while making execution order clear for operators.

Rejected: add more isolated warnings | phase gates make the next valid action clearer than scattered cautions.

Confidence: high

Scope-risk: narrow

Directive: when future release mistakes happen, update the relevant phase gate or state table first.

Tested: git diff --check

Not-tested: rendered documentation site
@debop debop added the documentation Improvements or additions to documentation label May 24, 2026
@debop debop self-assigned this May 24, 2026
@debop debop merged commit 4336328 into main May 24, 2026
2 checks passed
@debop debop deleted the docs/release-docs-clarity branch May 24, 2026 03:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant