[Infra] Git Tagging & Release Workflow

[mfittko]

Problem Statement

Production deployment needs a deterministic release contract.
Without strict tag semantics and workflow checks, production deploys can trigger
at the wrong time or without a traceable release artifact.

Scope

In scope:

• Tag naming policy
• GitHub release behavior for stable tags
• Validation for valid and invalid tag patterns
• Release checklist and operator guidance

Out of scope:

• Replacing the CI platform
• Environment-specific app behavior changes

Technical Approach

• Define the allowed tag patterns.
• Enforce production eligibility in automation.
• Require changelog or release-note generation for stable tags.
• Document the release checklist in the repository.

Dependencies

Hard dependencies: none
Blocks:

• CDK foundation and config contract
• CI/CD pipeline

Acceptance Criteria

• Versioning scheme documented
• Tag convention documented (v* and v*-stable)
• GitHub Actions creates releases on stable tags
• Releases include changelog/release notes
• Team understands the workflow

Proposed Definition Of Done

• Docs are merged in CONTRIBUTING or equivalent release docs.
• One successful stable-tag workflow run is linked.
• One invalid-tag rejection run is linked.
• Reviewer sign-off is recorded in the issue.

Validation Plan

1. Push a non-stable tag and confirm no production deploy path runs.
2. Push an invalid stable-like tag and confirm the workflow fails clearly.
3. Push a valid stable tag and confirm release creation.
4. Verify the release artifact contains generated changelog content.

Risks And Mitigations

• Risk: Tag validation blocks valid releases.
  • Mitigation: Add positive and negative workflow tests.
• Risk: Manual process drift.
  • Mitigation: Keep the checklist in-repo and link it from the pipeline story.

Handoff Notes

Coordinate workflow trigger rules with the CI/CD pipeline story so release logic
is defined once.

AC/DoD Coverage Matrix

Item	Type (AC/DoD/Non-goal)	Status (Met/Partial/Unmet/Unverified)	Evidence (spec/tests/behavior)	Notes
Versioning scheme documented	AC	Unverified	CONTRIBUTING update	Source AC
Tag convention documented (v* and v*-stable)	AC	Unverified	CONTRIBUTING update	Source AC
GitHub Actions creates releases on stable tags	AC	Unverified	Workflow run links	Source AC
Releases include changelog/release notes	AC	Unverified	Release artifact	Source AC
Team understands the workflow	AC	Unverified	Reviewer walkthrough sign-off	Source AC
Docs are merged in CONTRIBUTING or equivalent release docs.	DoD	Unverified	Docs diff	Proposed DoD
One successful stable-tag workflow run is linked.	DoD	Unverified	Workflow run link	Proposed DoD
One invalid-tag rejection run is linked.	DoD	Unverified	Workflow run link	Proposed DoD
Reviewer sign-off is recorded in the issue.	DoD	Unverified	Issue comment	Proposed DoD

[mfittko]

Refinement update applied. This issue now has explicit scope, hard dependencies, measurable acceptance criteria, a proposed Definition of Done, a validation plan, and an AC/DoD coverage matrix so it is ready for assignment.