Implement Release Finalization and Post-Release Workflows (C3-C4)

[hdamker]

Updated 2026-02-14: Aligned with actual design and implementation (PR #67 in tooling). Original description was based on the early concept from PR #338.

Problem description

After a release snapshot is prepared and reviewed, several manual steps remain: finalizing metadata, creating tags, publishing GitHub releases, and syncing artifacts back to main. These operations need automation.

Part of #191 (Develop automation support in support of release management). Part of #379 (Integration and roll-out of Release Automation).

Implemented solution

C3: Release Finalization and Publication

After the Release Preparation PR is merged (snapshot state becomes DRAFT_READY with a draft GitHub Release), the release manager triggers publication with /publish-release --confirm <tag>.

Steps:

1. Metadata finalization: Sets release_date in release-metadata.yaml, commits to snapshot branch
2. Git tag creation: Creates annotated tag rX.Y pointing to the finalization commit
3. GitHub Release publication: Transitions draft release to published, includes release-metadata.yaml and CHANGELOG content
4. Reference tag creation: Creates src/rX.Y tag on main at the branch point (marks commit for potential maintenance branch creation)
5. Branch cleanup: Deletes snapshot and release-review branches

C4: Post-Release Sync

Triggered automatically after publication:

1. Sync PR creation: Creates post-release/rX.Y branch from main (not from the release branch)
2. Selective sync (does NOT sync version fields — main stays in "wip" state):
   • Copies CHANGELOG/CHANGELOG-rX.md from the snapshot branch
   • Updates README "Release Information" section between delimiters with release metadata and links
3. PR for review: Creates PR to main with post-release and automated labels, requires manual approval

Release Issue Closure

Auto-closes the Release Issue and updates state to PUBLISHED.

Key design decisions

• Two-phase publish: PR merge creates a draft release; publication requires an explicit command. This gives release managers a final checkpoint.
• Immutable snapshots: Snapshot branches are not modified after creation (review changes go on the review branch). This prevents drift during the review period.
• Selective sync: Post-release PR copies only documentation artifacts (CHANGELOG, README). API version fields stay as "wip" on main to avoid disrupting ongoing development.

Deferred

• OpenAPI $ref bundling (see Commonalities#577)
• Maintenance branch workflow (C5, tracked in Implement Maintenance Branch Releases (C5 Workflow) #356)

Status

Implemented and tested. See tooling#69 (closed).

[hdamker]

Status update: the functionality was added to the MVP of the Release Automation workflow.

• Design changes and documentation additions are included in docs: add C3-C4 release publication and post-release design #374
• Development work in progress in https://github.com/hdamker/tooling/tree/release-automation-mvp
  • Technical architecture https://github.com/hdamker/tooling/blob/release-automation-mvp/release_automation/docs/technical-architecture.md

Next steps:

• Prerequisite: Extend release collector to upload release-metadata.yaml for pre-releases project-administration#118
• Integration into camaraproject/tooling
  • Branch strategy in tooling
  • Test repository/ies in camaraproject
  • E2E tests in camaraproject setting
  • Tests in repositories with legacy releases (version calculation)