Changelog Playbook

Publishing lifecycle

Changelog entries are committed in the same PR as the feature they describe. They deploy together when the PR merges. No second PR needed.

During feature development, run /changelog-entry to create the MDX file on the feature branch.

When to post

Post a changelog entry when:

A user-facing feature ships to production (merged to main)
A meaningful fix resolves a pain point users have reported
Pricing or policy changes take effect

Do not post for:

Internal refactors with no user-visible change
Bug fixes for unreleased features
Infrastructure changes users cannot perceive

Trigger checklist

When a GSD phase completes or a significant PR is ready, ask:

Is this user-facing?
Can you describe the change in one sentence without technical terms?
Would a nonprofit executive director care about this change?

If all three are yes, create an entry via /changelog-entry.

Post-merge checklist

After a feature PR merges, Claude checks:

Changelog entry included? If not and the criteria are met, create one on a quick docs/changelog-* branch.
Featurebase update needed? Did this close a feature request or advance a roadmap item? Run /featurebase-sync to update the roadmap item status.
Blog post needed? Is this a major release or strategic announcement? Draft a blog post separately.

Where entries live

MDX files in content/changelog/YYYY-MM-DD-short-slug.mdx. Metadata in frontmatter, content in the MDX body (Markdown bullets).

Format

Title — short, direct, outcome-first. Lead with what the nonprofit can now do.

Good: "Board reports, minus the suffering."
Bad: "Added PDF export feature."

Summary — one sentence in plain English for a nonprofit executive director. Max 200 characters.

Body — 3–6 Markdown bullet points.

Good: **AI Ask Anything** — natural language reporting across all your data
Bad: Implemented NLP query interface for data retrieval

Category — one of:

feature — new user-facing capability
ai — AI-powered tool or agent improvement
fix — bug fix or reliability improvement
pricing — pricing or plan changes
brand — visual, copy, or brand updates

Optional links:

blogPost: /blog/slug — for major releases with a blog post
featurebaseUrl: https://givelink.featurebase.app/p/slug — for features driven by user feedback

Examples

See content/changelog/ for the historical entries that seed the v1.0 through v2.0 backfill. Use those as the tone and format reference.

When to post

Post a changelog entry when:

A user-facing feature ships to production (merged to main)

A meaningful fix resolves a pain point users have reported

Pricing or policy changes take effect

Do not post for:

Internal refactors with no user-visible change

Bug fixes for unreleased features

Infrastructure changes users cannot perceive

Post-merge checklist

After a feature PR merges, Claude checks:

Changelog entry included? If not and the criteria are met, create one on a quick docs/changelog-* branch.

Featurebase update needed? Did this close a feature request or advance a roadmap item? Run /featurebase-sync to update the roadmap item status.

Blog post needed? Is this a major release or strategic announcement? Draft a blog post separately.

Format

Title — short, direct, outcome-first. Lead with what the nonprofit can now do.

Good: "Board reports, minus the suffering."

Bad: "Added PDF export feature."

Summary — one sentence in plain English for a nonprofit executive director. Max 200 characters.

Body — 3–6 Markdown bullet points.

Good: **AI Ask Anything** — natural language reporting across all your data

Bad: Implemented NLP query interface for data retrieval

Category — one of:

feature — new user-facing capability

ai — AI-powered tool or agent improvement

fix — bug fix or reliability improvement

pricing — pricing or plan changes

brand — visual, copy, or brand updates

Optional links:

blogPost: /blog/slug — for major releases with a blog post

featurebaseUrl: https://givelink.featurebase.app/p/slug — for features driven by user feedback