pr Release Workflow

Write PR descriptions that reviewers actually read, generate release notes from merged PRs (not memory), maintain a changelog that stays in sync, and apply semantic versioning consistently.

The Problem**

Your PR description says "fix bug in payment flow." Your release notes say "misc updates and improvements." Your CHANGELOG.md hasn't been updated since v0.8.3. Your team decides version numbers by gut feeling — "this feels like a minor" — and occasionally ships a "patch" that breaks the API. The root cause: writing the PR description, release notes, changelog entry, and version number as separate, disconnected tasks means they're never consistent. The PR is written at PR time (vague), the release notes are written at release time (from memory), and the changelog is written never.

What You Get

• PR description template — structured format with What/Why/How/Testing/Evidence/Checklist sections, enforced Conventional Commits title convention (feat(scope): imperative summary), and anti-pattern detection ("Update files per review comments" flagged as unhelpful)
• Release notes from PR data — gathers merged PRs via gh pr list, groups by impact (Highlights → Features → Bug Fixes → Breaking Changes), rewrites commit messages into user-facing sentences, and links every entry to its PR number
• Changelog integration — maintains CHANGELOG.md in Keep a Changelog format with [Unreleased] section that PRs add to during development, then rename to version+date at release time, with fixed vocabulary (Added/Changed/Deprecated/Removed/Fixed/Security)
• Semantic versioning decisions — reads the merged PR list and applies the rule: breaking change → MAJOR, new feature → MINOR, bug fix/perf → PATCH, with explicit reasoning documented next to the tag
• Release checklist — 7-point verification: CI green on main AND release commit, version bumped everywhere (with grep for stragglers), CHANGELOG entry present with real date, no leftover [Unreleased] content, tag points at correct commit, docs updated, migration notes present for breaking changes

Why This Beats Prompting It Yourself

When you ask an agent to "write release notes," it guesses what was in the release based on commit messages — inventing features that were cut, missing breaking changes, and using developer jargon instead of user-facing language. This skill enforces a ground-truth workflow: gather PR data from GitHub (gh pr list --state merged), cross-check against git log, rewrite into impact statements, and link every entry to a real PR number. Release notes are never written from memory — they're derived from the actual merged PRs.

Example Session

You: Write a PR description for my payment retry branch.

Agent:

## What
Retries failed webhook deliveries up to 3 times with exponential backoff instead of dropping them after the first failure.

## Why
Closes #482. Customers reported missed fulfillment events when Stripe's webhook endpoint briefly returned 502s (~0.4% of deliveries over the last 30 days).

## How
- Adds `retryWebhook()` with backoff 1s → 4s → 16s and jitter
- Marks delivery `failed` only after the 3rd attempt returns non-2xx
- Persists attempt count on `webhook_deliveries.attempts` for observability

## Testing
- [x] Unit: backoff sequence, jitter bounds, non-2xx classification (429 treated as retryable)
- [x] Integration: simulated 502-then-200 sequence delivers exactly once
- [ ] Manual: staged run against Stripe test-mode events

## Evidence
Before: 99.6% delivery success (last 30d, staging logs)
After (chaos test, 100 forced 502s): 100% success, p95 delivery latency +2.1s on retried events

Use Cases

• Writing PR descriptions for a team that uses AI agents to generate most of the code
• Generating release notes for a monthly release from 15+ merged PRs
• Maintaining a CHANGELOG.md that stays in sync with actual releases
• Deciding the next version number based on what actually shipped (not gut feeling)
• Running a release checklist that catches the 7 most common pre-release mistakes

Known Limitations

The workflow assumes Conventional Commits convention for PR titles — if the team doesn't use it, the release notes grouping (Features/Bug Fixes/Breaking Changes) won't work correctly. Pre-1.0 projects need an explicit versioning policy documented in the changelog header to avoid surprises. The release checklist requires gh CLI and GitHub repository access for PR data gathering.

---

Tags: git github releases changelog semver conventional-commits developer-experience

Version: 1.0.0