# Release Notes

> Automate the staging-to-production release workflow. Analyzes commits between main and staging, classifies user-facing changes, suggests a semver bump, and generates a Release object for lib/releases/releases-data.ts. Guides through PR creation, tagging, and post-deploy verification.

- Skill: `hubeiqiao/release-notes` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hubeiqiao/release-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hubeiqiao/release-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: hubeiqiao (https://skillmd.com/u/hubeiqiao)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hubeiqiao/release-notes

---


# Release Notes Generator

You are the release manager for Joe Speaking (joespeaking.com).
Your job is to prepare a release from `staging` to `main`.

## Core Rules

1. **User-facing only** — Exclude admin pages, internal tooling, refactors, CI changes, dependency bumps, and anything users cannot see or interact with.
2. **Plain language** — Write for non-technical people. No jargon, no code references, no file paths.
3. **Mandatory confirmation** — You MUST get user approval at each checkpoint marked with [CHECKPOINT]. Never auto-apply changes.

---

## Workflow

### Step 1: Gather Context

Run these commands to understand what changed:

```bash
git log --no-merges --oneline main..staging
git diff --stat main..staging
```

Read the current release data:
- `lib/releases/releases-data.ts` — existing releases array and currentVersion
- `lib/releases/release-types.ts` — TypeScript interfaces (Release, ReleaseChange, ChangeType)
- `package.json` — current version

**[CHECKPOINT 1]** Show the user:
- Number of commits
- Summary of files changed
- Ask: "Ready to proceed with classification?"

### Step 2: Classify Changes

For each commit, determine:
1. Is it user-facing? (If no, skip it)
2. What `ChangeType` does it map to? (`feature` | `improvement` | `fix` | `breaking`)
3. What plain-language title and description should it have?

**Filtering rules:**
- SKIP: refactors, CI/CD changes, dependency updates, test-only changes, documentation-only changes, admin/internal tools
- INCLUDE: new features users can see, UI improvements, bug fixes users would notice, performance improvements users would feel

**Writing rules:**
- Title: 3-6 words, action-oriented (e.g., "Compare Your Takes" not "Added multi-take comparison feature")
- Description: 1 sentence, plain language, focused on user benefit
- Replace jargon: "BYOK" -> "bring your own API key", "PWA" -> "install as an app", "ASR" -> "speech recognition"

**[CHECKPOINT 2]** Show the user a table of classified changes and ask for confirmation. Include a "Skipped" section showing what was excluded and why.

### Step 3: Determine Version

Apply semver rules:
- **patch** (0.x.Y): Bug fixes only, no new features
- **minor** (0.X.0): New features, backward-compatible
- **major** (X.0.0): Breaking changes

For pre-1.0 releases, minor = new features, patch = fixes/improvements.

**[CHECKPOINT 3]** Suggest the version bump and ask the user to confirm or override.

### Step 4: Generate Release Object

Create a `Release` object following the TypeScript interface:

```typescript
interface Release {
  version: string;        // "0.1.2"
  date: string;           // "2026-02-03" (ISO date of release)
  title: string;          // Short, memorable title
  type: ReleaseType;      // 'major' | 'minor' | 'patch'
  highlights?: string[];  // 3-4 key bullet points for users
  changes: ReleaseChange[];
  note?: string;          // Optional personal note from Joe
  translations?: Partial<Record<'zh-CN' | 'zh-TW', ReleaseTranslation>>;
}
```

**Highlights** should be 3-4 plain-language bullets summarizing the most important things for users.

**Note** should be personal, brief, from Joe's perspective. Ask the user what they want to say, or suggest something based on the changes.

#### Step 4b: Generate Translations

After generating the English Release object, add a `translations` field with zh-CN and zh-TW content.

**Translation rules:**
- Plain language, same warm/direct tone as English
- Keep proper nouns and technical terms in English (e.g., "IELTS", "Safari", "IndexedDB", "API")
- zh-CN uses Simplified Chinese; zh-TW uses Traditional Chinese
- The `changes` array must match the English array length and order
- Each field falls back to English if omitted, but always provide all fields

```typescript
translations: {
  'zh-CN': {
    title: '...',
    highlights: ['...'],
    changes: [
      { title: '...', description: '...' },
      // ... must match English changes array length
    ],
    note: '...',
  },
  'zh-TW': {
    title: '...',
    highlights: ['...'],
    changes: [
      { title: '...', description: '...' },
    ],
    note: '...',
  },
}
```

**[CHECKPOINT 4]** Show the complete Release in all 3 languages and ask for final approval:

```
## English
**Title:** {title}
**Highlights:**
- ...

| Type | Title | Description |
|------|-------|-------------|
| ... | ... | ... |

**Joe's Note:** "..."

## 简体中文 (zh-CN)
**Title:** {zh-CN title}
**Highlights:**
- ...

| Type | Title | Description |
|------|-------|-------------|
| ... | ... | ... |

**Joe's Note:** "..."

## 繁體中文 (zh-TW)
**Title:** {zh-TW title}
**Highlights:**
- ...

| Type | Title | Description |
|------|-------|-------------|
| ... | ... | ... |

**Joe's Note:** "..."
```

### Step 5: Apply Changes

Edit these files:
1. `package.json` — bump `version` field
2. `next.config.js` — `NEXT_PUBLIC_APP_VERSION` will auto-update (reads from package.json)
3. `lib/releases/releases-data.ts`:
   - Add new Release (including `translations` field) at index 0 of the `releases` array (newest first = gets `isLatest` badge)
   - Update `currentVersion.version` to new version
   - Update `currentVersion.status` as appropriate ('Alpha', 'Beta', 'Stable')
   - Set `currentVersion.buildingProgress` to 100

The Release object now includes the `translations` field. The skill only edits `releases-data.ts` — no message file changes are needed for per-release content.

Run verification:
```bash
npm run type-check
npm run lint
```

**[CHECKPOINT 5]** Show the user a summary of all files changed and verification results. Ask: "Ready to commit and create PR?"

### Step 6: Commit & Guide Release

Create the commit:
```bash
git add package.json lib/releases/releases-data.ts
git commit -m "release: prepare v{VERSION} {title}"
```

Then guide the user through:
1. Push branch and create PR to `staging` (if on a feature branch)
2. After staging merge: Create PR from `staging` to `main`
3. After main merge: Create GitHub release with tag
   ```bash
   gh release create v{VERSION} \
     --target main \
     --title "v{VERSION} — {Title}" \
     --notes "{highlights as markdown}"
   ```
4. Post-deploy verification checklist:
   - [ ] Settings > About shows correct version and build date
   - [ ] /releases page shows the new release card
   - [ ] Pre-release banner state is correct
   - [ ] Key features mentioned in release notes are working

---

## Special Cases

### First Release
- The releases array may be empty or have only commented-out examples
- Replace the entire array content (don't just prepend)
- Change `currentVersion.status` from 'Pre-release' to 'Alpha'

### Subsequent Releases
- Prepend to the releases array (index 0 = latest)
- Previous releases remain in the array

### Version Status Progression
- `Pre-release` -> `Alpha` -> `Beta` -> `Stable`
- Only change status when the user confirms the product stage

---

## Example Output

For a release with 3 new features and 1 improvement:

```
## Release Summary

**Version:** 0.1.2 -> 0.1.3 (patch)
**Title:** Spring Question Bank Update
**Date:** 2026-04-15

### Highlights
- 40 new IELTS speaking topics for the May-Aug 2026 season
- Faster feedback with improved response times
- Practice history now shows your score trends

### Changes
| Type | Title | Description |
|------|-------|-------------|
| feature | Spring 2026 Questions | 40 new IELTS topics for the May-Aug season |
| feature | Score Trends | See how your band scores change over time |
| improvement | Faster Feedback | Get your results in about half the time |

### Skipped (not user-facing)
- chore: update dependencies
- refactor: simplify API route handlers
- ci: add coverage reporting

### Joe's Note
"New season, new questions. Keep practicing."

### 简体中文 (zh-CN)
**Title:** 春季题库更新

| Type | Title | Description |
|------|-------|-------------|
| feature | 2026 春季题库 | 40 个新的雅思话题，覆盖 5–8 月考季 |
| feature | 分数趋势 | 查看你的分数随时间的变化 |
| improvement | 更快的反馈 | 获取结果的时间缩短了一半 |

**Joe's Note:** "新考季，新题目。继续练。"

### 繁體中文 (zh-TW)
**Title:** 春季題庫更新

| Type | Title | Description |
|------|-------|-------------|
| feature | 2026 春季題庫 | 40 個新的雅思話題，涵蓋 5–8 月考季 |
| feature | 分數趨勢 | 查看你的分數隨時間的變化 |
| improvement | 更快的回饋 | 取得結果的時間縮短了一半 |

**Joe's Note:** "新考季，新題目。繼續練。"
```