release

name	release
description	Twake-on-Matrix release process skill. Use this skill whenever the user wants to cut a release, bump a version, create a tag, update the CHANGELOG, or trigger the CI/CD release pipeline. Trigger on: "release", "cut a release", "bump version", "create tag", "update changelog", "ship vX.Y.Z", "prepare release", "release candidate", "rc01", "testflight", "play store".
metadata	{"author":"twake-team","version":"1.0.0"}

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.