Re-land release/version SOP with v1.1.0 audit lessons #111

New Issue

2026-07-02T18:07:55-05:00

sysadmin commented

2026-07-02 18:07:55 -05:00

Summary

Re-land the missing release/version SOP and include the lessons learned from the v1.1.0 release audit.

Problem

The release SOP work (#68 / PR #82) was previously closed without merging, so the release/version SOP is still absent from master.

During the v1.1.0 release, several issues had to be corrected manually:

release branch went stale multiple times
changelog missed merged items
closed-without-merge PRs were mistakenly treated as landed
Implements #N did not close tracker issues
changelog had to be regenerated after late merges
tag creation needed careful verification against the final master merge commit

Scope

Create or re-land the release/version SOP documentation.

The SOP should cover:

release branch creation
keeping release branch synced with latest master
regenerating changelog after the final feature PR merges
verifying every changelog-claimed issue actually landed in master
detecting closed-but-unmerged PRs
distinguishing Closes/Fixes from Implements/Refs
verifying issue state vs file presence on master
pre-tag checklist
tag target verification
tag push verification
post-release cleanup

Required checks to document

Before tagging:

fetch/prune/tags
verify open PRs
verify release branch is current
verify changelog contains only landed work
verify excluded issues/PRs are explicitly noted
grep/log master for files claimed in changelog
confirm final master merge commit
dry-run release-tag script if available
create tag only after merge
verify tag points to final master merge commit

Non-goals

Do not cut a release.
Do not create/move/delete/push tags.
Do not change release tooling unless explicitly scoped in a follow-up.
Do not implement profiles.json v2.

Acceptance criteria

Release/version SOP exists on master.
SOP includes v1.1.0 audit lessons.
SOP explicitly handles stale release branches.
SOP explicitly handles closed-without-merge PRs.
SOP explicitly says Implements #N does not close issues.
SOP requires file/master verification before reporting merged work.
SOP requires tag target verification before pushing.

Related: #68 (closed without merge — predecessor), #51 (closed-not-merged reconciliation rules), #50 (release-tag helper).

## Summary Re-land the missing release/version SOP and include the lessons learned from the v1.1.0 release audit. ## Problem The release SOP work (#68 / PR #82) was previously closed without merging, so the release/version SOP is still absent from master. During the v1.1.0 release, several issues had to be corrected manually: - release branch went stale multiple times - changelog missed merged items - closed-without-merge PRs were mistakenly treated as landed - `Implements #N` did not close tracker issues - changelog had to be regenerated after late merges - tag creation needed careful verification against the final master merge commit ## Scope Create or re-land the release/version SOP documentation. The SOP should cover: - release branch creation - keeping release branch synced with latest master - regenerating changelog after the final feature PR merges - verifying every changelog-claimed issue actually landed in master - detecting closed-but-unmerged PRs - distinguishing `Closes/Fixes` from `Implements/Refs` - verifying issue state vs file presence on master - pre-tag checklist - tag target verification - tag push verification - post-release cleanup ## Required checks to document Before tagging: - fetch/prune/tags - verify open PRs - verify release branch is current - verify changelog contains only landed work - verify excluded issues/PRs are explicitly noted - grep/log master for files claimed in changelog - confirm final master merge commit - dry-run release-tag script if available - create tag only after merge - verify tag points to final master merge commit ## Non-goals - Do not cut a release. - Do not create/move/delete/push tags. - Do not change release tooling unless explicitly scoped in a follow-up. - Do not implement profiles.json v2. ## Acceptance criteria - Release/version SOP exists on master. - SOP includes v1.1.0 audit lessons. - SOP explicitly handles stale release branches. - SOP explicitly handles closed-without-merge PRs. - SOP explicitly says `Implements #N` does not close issues. - SOP requires file/master verification before reporting merged work. - SOP requires tag target verification before pushing. Related: #68 (closed without merge — predecessor), #51 (closed-not-merged reconciliation rules), #50 (release-tag helper).

sysadmin added the documentation release workflow labels 2026-07-02 18:08:16 -05:00

jcwalker3 referenced this issue

2026-07-02 18:08:40 -05:00

Document Controller Handoff Summary and LLM workflow requirements #101

jcwalker3 added the status:in-progress label 2026-07-02 19:52:34 -05:00

jcwalker3 referenced this issue from a commit

2026-07-02 19:53:26 -05:00

docs: re-land release version SOP with v1.1.0 audit lessons (#111)

jcwalker3 referenced a pull request that will close this issue

2026-07-02 19:53:27 -05:00

docs: re-land release version SOP with v1.1.0 audit lessons (#111) #119

jcwalker3 referenced this issue from a commit