release-plannotator

# Plannotator Release

The process has four phases. Phase 1 (release notes) is where most of the work happens — present the draft for review before proceeding to later phases.

## Phase 1: Draft Release Notes

This is the most important phase. The release notes are the public face of each version and the primary way the community sees their contributions recognized.

### Step 1: Determine scope

1. Find the latest release tag: `git tag --sort=-v:refname | head -1`
2. Determine the new version number. Ask the user if unclear (patch, minor, or major).
3. Gather all changes since the last tag:
   - `git log --oneline <last-tag>..HEAD` for commit history
   - `git log --merges --oneline <last-tag>..HEAD` for merged PRs
4. For each PR, use `gh pr view <number> --json title,author,body,closedIssues,labels` to get details.

### Step 2: Research contributors

This is critical. Every person who participated in the release gets credit — not just PR authors.

For each PR and linked issue, collect:
- **PR authors** — the person who wrote the code
- **Issue reporters** — who filed the bug or feature request
- **Issue commenters** — who participated in the discussion with useful context
- **Discussion creators** — who started relevant GitHub Discussions
- **Feature requestors** — check the linked "closes #N" issues and their authors

Use the GitHub API via `gh`:
```bash
# Get issue details including author
gh issue view <number> --json author,title,body

# Get issue comments to find participants
gh api repos/backnotprop/plannotator/issues/<number>/comments --jq '.[].user.login'

# Get PR review comments
gh api repos/backnotprop/plannotator/pulls/<number>/comments --jq '.[].user.login'
```

### Step 3: Write the release notes

Read the reference release notes in `references/` for the canonical template structure. These are real release notes from previous versions — match their tone, structure, and level of detail.

- `release-notes-v0.13.0.md` — large release, 14 PRs, 3 first-time contributors, "New Contributors" + narrative "Contributors" section
- `release-notes-v0.12.0.md` — large community release, 14 PRs, 10 external, detailed narrative "Contributors" section
- `release-notes-v0.13.1.md` — small patch release, 2 PRs, no external authors, "Community" section focused on issue reporters

Pay attention to how each reference handles contributor crediting differently. Pick the pattern that fits the release's contributor profile — a release with many external PRs warrants a narrative "Contributors" section; a patch driven by issue reports uses a lighter "Community" section.

Write the file to the repo root as `RELEASE_NOTES_v<VERSION>.md`.

#### Structure

1. **X/Twitter follow link** — first line, always the same:
   ```
   Follow [@plannotator](https://x.com/plannotator) on X for updates
   ```

2. **"Missed recent releases?"** collapsible table — copy from the previous release's notes, then:
   - Add the previous release (the one you're succeeding) as the newest row
   - Keep roughly 10-12 rows; drop the oldest if needed
   - Each row: version link + comma-separated feature highlights (short phrases)

3. **"What's New in vX.Y.Z"** — the heart of the notes
   - Open with 1-3 sentences summarizing the release theme and scope. Mention how many PRs, how many from external contributors, any first-timers.
   - Each major feature/fix gets its own `###` subsection with:
     - A descriptive heading (not the PR title verbatim — rephrase for clarity)
     - 1-4 paragraphs explaining what changed and why it matters. Be specific and concrete. Describe the problem that existed before, what the change does, and how users experience it.
     - Credit line at the bottom: PR link, linked issues with `closing [#N]`, and contributor attribution
   - Minor changes go under `### Additional Changes` as bold-titled bullets

4. **Install / Update** — standard block, read from the previous release notes and reuse verbatim

5. **"What's Changed"** — bullet list of every PR in the release:
   ```
   - feat: descriptive PR title by @author in [#N](url)
   ```

6. **"New Contributors"** — if any first-time contributors:
   ```
   - @username made their first contribution in [#N](url)
   ```

7. **"Contributors" or "Community"** — narrative section recognizing everyone who participated:
   - PR authors get a sentence about what they built
   - Issue reporters and commenters get listed with what they reported/discussed
   - Group community issue reporters in a bullet list at the end

8. **Full Changelog link**:
   ```
   **Full Changelog**: https://github.com/backnotprop/plannotator/compare/<prev-tag>...<new-tag>
   ```

#### Writing guidelines

- **Narrative over noise.** Write in clear, readable prose. Not marketing-speak, not changelog-dump. Explain what changed and why someone should care, in plain language.
- **Bullets where they help.** Use bullet lists for enumerating discrete items (additional changes, contributor lists). Use paragraphs for explaining features.
- **No cliches or buzzwords.** Don't say "exciting", "game-changing", "seamless", "powerful". Just describe what happened.
- **No punchlines.** Don't end sections with a clever quip or a summary zinger. Let the feature speak for itself.
- **Speak through practical benefit.** Describe what changed and what it means for the user in concrete, reliable terms. Not aspirational, not hype — just what it does.
- **Don't overuse em dashes.** One or two per release is fine. If you notice them stacking up, restructure the sentence instead.
- **Grammatical structure matters.** Vary sentence structure. Active voice. Concrete subjects and verbs.
- **Contributor tags.** Use `@username` — bare at-mentions, not markdown links like `[@user](url)`. GitHub renders bare `@mentions` with avatar icons in release notes. This is important for community recognition.
- **Every contributor counts.** Everyone who filed an issue, left a comment that shaped a decision, or participated in a discu