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

# 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/

• 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 discussion gets mentioned. This project's community is its lifeblood.

Step 4: Present for review

Write the draft to

RELEASE_NOTES_v<VERSION>.md

git add

Phase 2: Version Bump

Bump the version string in these 7 files (and only these — other package.json files use stub versions):

package.json

"version"

apps/opencode-plugin/package.json

"version"

apps/pi-extension/package.json

"version"

apps/hook/.claude-plugin/plugin.json

"version"

apps/copilot/plugin.json

"version"

openpackage.yml

version:

packages/server/package.json

"version"

Read each file, confirm the current version matches expectations, then update all 7 atomically.

Do not bump the VS Code extension (

apps/vscode-extension/package.json

Phase 3: Build

Run builds in dependency order:

bun run build:review    # 1. Code review editor (standalone Vite build)
bun run build:hook      # 2. Plan review + hook server (copies review's built HTML into hook dist)
bun run build:opencode  # 3. OpenCode plugin (copies built HTML from hook + review)
bun run build:pi        # 4. Pi extension (chains review → hook → pi internally, safe to run after 1-2)

build:pi

Verify all builds succeed before proceeding.

Pi Parity Gate

After builds pass, audit the Pi extension to ensure all server-side imports resolve in the published package. This catches missing files before they reach npm.

1. Check imports vs

   files

   array. Trace all local imports (starting with

   ./

   or

   ../

   ) from

   index.ts

   ,

   server.ts

   ,

   tool-scope.ts

   , and every file in

   server/

   . Verify each target is covered by a pattern in the

   files

   array of

   apps/pi-extension/package.json

   .

2. Check

   vendor.sh

   covers all shared/ai imports. Every

   ../generated/*.js

   import in the server files must have a corresponding entry in

   vendor.sh

   's copy loops. If a new shared module or AI module was added to

   packages/shared/

   or

   packages/ai/

   and is imported by Pi's server code, it must be added to

   vendor.sh

   .

3. Dry-run the pack. Run

   cd apps/pi-extension && bun pm pack --dry-run

   and verify the output includes every file the server imports. Look specifically for any newly added files since the last release.

4. Quick smoke test. Confirm

   generated/

   contains all expected files after build, especially any new ones (e.g., a new shared module added in this release cycle).

If anything is missing, fix it before proceeding to Phase 4. Common fixes:

• Add the file to

  vendor.sh

  's copy loop
• Add the file or directory to the

  files

  array in

  package.json

• Add an import path fix (Pi uses

  ../generated/

  not

  @plannotator/shared

  or

  @plannotator/ai

  )

Phase 4: Commit, Tag, and Release

1. Commit the version bump:

   chore: bump version to X.Y.Z
   

   Stage only the 7 version-bumped files. Do not stage the release notes file (it's untracked by design).

2. Create and push the tag:

   git tag vX.Y.Z
   git push origin main
   git push origin vX.Y.Z
   

   The

   v*

   tag push triggers the release pipeline (

   .github/workflows/release.yml

   ).

3. The pipeline handles everything else:

   • Runs tests
   • Cross-compiles binaries for 6 platforms (macOS ARM64/x64, Linux x64/ARM64, Windows x64/ARM64)
   • Compiles paste service binaries (same 6 platforms)
   • Generates SLSA build provenance attestations for all 12 binaries via

     actions/attest-build-provenance

     (signed through Sigstore, recorded in Rekor)
   • Creates the GitHub Release with all binaries attached
   • Publishes

     @plannotator/opencode

     and

     @plannotator/pi-extension

     to npm with provenance

   Note on immutable releases: The repo has GitHub Immutable Releases enabled, so once the

   v*

   tag is pushed and the release is created, the tag→commit and tag→asset bindings are permanent. You cannot delete and re-create a tag to "fix" a bad release — you must ship a new version. Release notes remain editable (see step 5), but everything else is locked.

4. Monitor the pipeline: Watch the release workflow run until it completes:

   gh run list --workflow=release.yml --limit=1
   gh run view <run-id> --log
   

   Verify:

   • All jobs pass (test, build, release, npm-publish)
   • The GitHub Release was created with all binary artifacts
   • npm packages published successfully (check with

     npm view @plannotator/opencode version

     and

     npm view @plannotator/pi-extension version

     )

   If anything fails, investigate the logs and report to the user before retrying.

5. Replace the release notes: Once the release is live and verified, replace the auto-generated notes body with the drafted release notes:

   gh release edit vX.Y.Z --notes-file RELEASE_NOTES_v<VERSION>.md
   

Checklist

Before tagging, verify:

• All 7 version files bumped consistently
• Release notes drafted and reviewed

• bun run build:review

  succeeded

• bun run build:hook

  succeeded

• bun run build:opencode

  succeeded

• bun run build:pi

  succeeded (or pi-specific build step)
• Version bump committed
• Pi parity gate passed (imports, vendor.sh, dry-run pack)
• No stale build artifacts (clean builds, no cache issues — run

  bun install

  first if dependencies changed)

After tagging, verify:

• Release workflow completed (all 4 jobs green)
• GitHub Release created with all binaries
• npm packages published at correct version
• Release notes replaced via

  gh release edit