Release plan issue

Produces one GitHub issue that the release team works through, top to bottom, on release day. It is a checklist, not a report. The reference for the right amount of detail is F3-Nation/f3-nation#1068. Never write more than that; shorter is better.

The Staging test plan is a separate issue made by the staging-test-plan skill. Do not put test steps in this issue.

Inputs

Ask for anything missing before starting:

1. Release PR number — the open (or just-merged) chore: release main PR opened by release-please.
2. Environment — Staging (default) or Production.

Steps

1. Read the release PR.

   gh pr view <PR> --json title,body,state,mergedAt --jq '{title,state,mergedAt,body}'
   

   The body is the changelog: one <details> block per app, listing the merged PRs and issues. Note which apps are releasing. Ignore the version numbers — they never go in the issue.

2. Find new database migrations. The previous release is the last chore: release main commit on main before this PR's changes:

   git fetch origin main
   # Release PR still open: diff the last release against main.
   PREV=$(git log origin/main --grep '^chore: release main' --format=%H -n 1)
   END=origin/main
   # Release PR already merged: diff the release before it against this release's merge.
   # END=$(git log origin/main --grep '^chore: release main (#<PR>)' --format=%H -n 1)
   # PREV=$(git log "$END^" --grep '^chore: release main' --format=%H -n 1)
   git diff --name-only --diff-filter=A "$PREV" "$END" -- packages/db/drizzle/'*.sql'
   

   No new .sql files → no migration: drop Step 2 and the Database queries section from the template. Otherwise fill {{NEWEST_MIGRATION_FILE}} with the last file name listed.

3. Skim the linked PRs only for risk. For each changelog entry, read the PR title and, if needed, the first lines of its body. You are looking for exactly three things:

   • what a non-developer would call the headline change (for the Overview),
   • anything that breaks while the apps and database are out of step,
   • anything that goes straight to production (Homepage always does).

   Do not summarize every PR.

4. Fill in template.md. Follow the rules below. Delete every <!-- ... --> comment and every block marked optional that does not apply. Replace every {{PLACEHOLDER}}.

5. Write the draft to a local file, e.g. release-plan-<PR>.md in a scratch/temp directory (not in the repo). Show it to the person who asked and stop until they approve or request changes.

6. File the issue only after approval, following the repo github skill.

   gh issue create --title "Release plan: <short release name> to <Environment> (#<PR>)" \
     --body-file <draft file>
   

   No labels, no assignees. If gh is not available, suggest installing the GitHub CLI. If it still isn't available, stop after step 5 and tell the person to paste the draft into a new issue.

Rules for the content

• Audience: volunteers who are not all developers. Plain words; explain a term the first time only if they must act on it.
• Never add a section beyond the ones in the template.
• Only the risky checklist steps get Watch, Expected, and Stop if sub-bullets, one line each.
• Database queries are read-only. Write them from the migration SQL; keep to the few that prove the migration applied and that nothing drifted.
• People: refer to roles, never names or handles. The template's Who's who table is the only place people are named; never invent people or roles. When the team changes, edit that table.
• Analytics ships separately. Leave it out even if it appears in the changelog.

Staging vs Production

The template is written for Staging. For a Production release, use the Production column of each row while filling it in.

	Staging	Production
Step 1 action	Merge the release PR; staging deploys start automatically	Approve each paused deploy-prod job (environment *-production) on the Actions page
Migration order	Deploy, then migrate	Migrate before approving if Staging's "Expected" line was not "none", unless the migration breaks the old app; say which in the Overview
Homepage	Already published to production when the PR merges — say so in the Overview	Nothing to do
Database	Cloud SQL f3data-nonprod, database f3_staging	Cloud SQL f3data, database f3_prod
Cloud Run and log links	As in the template	Drop -staging from each project ID
Step 3 (test plan)	Create the Staging test plan	Drop the step
Test step	Run the Staging test plan issue	Repeat only the per-app smoke checks from the Staging test plan against production URLs
Database queries	Run against f3_staging	Run against f3_prod
Last step	Let it run 24–48 h, then go/no-go for Production	Announce done in #monorepo

What to leave out

These made past plans too long. Do not include them:

• Version numbers, tag names, or per-app version tables.
• A per-PR summary of the changelog.
• Background on how release-please, Cloud Run, or migrations work.
• Anything about testing features — that belongs in the test plan.
• Placeholder rows for people who are not in the Who's who table.