release

Release Process Skill

Full reference: docs/adr/0036-release-process.md

This skill guides cutting a Twake-on-Matrix release end-to-end. Does NOT handle: hotfix branching, Play Store promotion, App Store Connect promotion (manual steps post-CI).

Default (no arguments)

Ask the user which step they want via AskUserQuestion:

• Full release (all steps)
• Step 1 — Confirm branch & HEAD
• Step 2 — Update CHANGELOG
• Step 3 — Bump version
• Step 4 — Tag & push
• Step 5 — Check CI status

Arguments

• full [vX.Y.Z] — run all steps for the given version
• changelog [vX.Y.Z] — draft CHANGELOG section for next version
• bump [vX.Y.Z] — update version in pubspec.yaml + stage commit
• tag [vX.Y.Z] — create annotated tag and push
• status — show CI workflow run status for latest tag

Step-by-Step Instructions

Step 1 — Confirm branch & HEAD

Run these to gather context, then show the user a confirmation prompt:

git branch --show-current            # current branch
git log -1 --oneline                 # last commit (sha + message)
git status --short                   # must be clean

Use AskUserQuestion to confirm before proceeding:

Release confirmation

"You are about to release from branch <branch>.

Last commit: <sha> <message>

Do you want to continue?"

Options: "Yes, proceed" / "No, abort"

Abort if the working tree is dirty (uncommitted changes) — ask user to stash or commit first. Branch choice is intentional; do not enforce main.

Step 2 — Update CHANGELOG.md

Insert new section at the TOP of CHANGELOG.md:

## [x.y.z] - YYYY-MM-DD
### Added
- TW-XXXX: Short description ≤80 chars

### Changed
- TW-XXXX: Short description ≤80 chars

### Fixed
- TW-XXXX: Short description ≤80 chars

CHANGELOG rules (enforced):

• One line item per TW-XXXX ticket (merge all commits sharing same ID)
• ≤ 80 characters per line, ≤ 2 lines per item — no exceptions
• No-ticket commits → short imperative phrase, same ≤80/≤2 rule

To collect commit messages since last tag:

git log $(git describe --tags --abbrev=0)..HEAD --oneline

Step 3 — Bump version in pubspec.yaml

Current format: version: x.y.z+2330

• Change x.y.z to the new version string
• Do NOT touch the +2330 build number — CI/CD manages it

Stage the bump commit (CHANGELOG + pubspec.yaml only):

git add CHANGELOG.md pubspec.yaml
git commit -m "chore: bump version to vx.y.z"

Step 4 — Tag and push

git tag vx.y.z                        # stable: v2.21.7
# or for RC: git tag v2.21.7-rc01
git push origin HEAD
# stable:
git push origin refs/tags/vx.y.z
# RC:
# git push origin refs/tags/vx.y.z-rcNN

Tag push triggers both CI workflows automatically.

Step 5 — CI/CD workflows (auto-triggered)

| File | Trigger | Effect | |---|---|---| | .github/workflows/release.yaml | tag v*.. | Android APK→Play Store internal; iOS IPA→TestFlight; GitHub Release | | .github/workflows/image.yaml | tag v*.. | Docker image→Docker Hub + GHCR tagged vx.y.z + release |

Check status:

gh run list --workflow=release.yaml --limit 5
gh run list --workflow=image.yaml --limit 5

Step 6 — Post-CI deployment

| Platform | Manual action needed | |---|---| | TestFlight | Promote build in App Store Connect | | Play Store | Promote from internal → alpha/beta/production in Play Console | | Docker | Update Helm values / deployment manifests to vx.y.z image tag |

Security Policy

This skill only executes git, gh, and read operations on the local repo. It does NOT push secrets, credentials, or env files. Refuse requests to skip CI, force-push tags, or bypass signing.