[Infra] Git Tagging & Release Workflow

[mfittko]

Summary

Establish a standardized git tagging and GitHub release workflow to support automated deployments.

Related: #174 (AWS ECS Deployment)

---

Context

The AWS deployment strategy (#174) uses git tags to trigger production deployments:

• *-stable tags → Production ECR + ECS deploy
• Push to main → Optional staging deploy

This issue defines the release workflow that feeds into that deployment pipeline.

---

Proposed Workflow

Versioning Scheme

Semantic Versioning (MAJOR.MINOR.PATCH):

• v1.0.0 - Initial production release
• v1.1.0 - New features (backwards compatible)
• v1.1.1 - Bug fixes
• v2.0.0 - Breaking changes

Tag Suffix Convention

Tag	Purpose	Deploys To
v1.2.3	Release candidate	Staging (if enabled)
v1.2.3-stable	Production release	Production

Release Process

flowchart LR
    A[Feature PRs] --> B[main branch]
    B --> C[Create tag v1.2.3]
    C --> D[Test in staging]
    D --> E[Promote: v1.2.3-stable]
    E --> F[Production deploy]
    F --> G[GitHub Release]

Loading

1. Merge to main - Features/fixes merged via PR
2. Create release tag - git tag v1.2.3 && git push --tags
3. Test in staging - Verify deployment works
4. Promote to stable - git tag v1.2.3-stable && git push --tags
5. Create GitHub Release - With changelog

---

Tasks

Git Workflow

• Document versioning scheme in CONTRIBUTING.md
• Add tag naming convention guidelines
• Create release checklist template

GitHub Actions

• Add workflow to create GitHub Release on *-stable tags
• Auto-generate changelog from PR titles/commits
• Optionally: Release drafter for draft releases

Optional Automation

• make release VERSION=1.2.3 - Create release tag
• make promote VERSION=1.2.3 - Add -stable suffix
• Pre-release validation (tests must pass)

---

Example Workflow

# After merging features to main
git checkout main && git pull

# Create release candidate
git tag v1.2.3
git push --tags
# → Triggers staging deploy (if enabled)

# After testing, promote to production
git tag v1.2.3-stable
git push --tags
# → Triggers production deploy + GitHub Release

---

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

---

Priority

Medium - Not a strict blocker for AWS deployment (can manually tag), but should be done early in Phase 4 (CI/CD Pipeline).

---

References

• AWS Deployment Epic: [Epic] AWS ECS Production Deployment with CDK #174
• Semantic Versioning
• GitHub Release Drafter