/changelog

name: changelog
description: Add a new changelog entry to docs/changelog-entries/
disable-model-invocation: true

Changelog

Add changelog entries as individual files in `docs/changelog-entries/`, then regenerate `docs/changelog.mdx` before opening or updating the PR.

Use a single long-lived branch for changelog automation: `automation/changelog`. The automation should update the existing open changelog PR from that branch when possible instead of opening multiple concurrent changelog PRs.

Principles

1. **User-facing only.** No infrastructure, CI, security hardening, billing internals, queue fixes, cron changes, self-hosting features, or anything users don't directly see or interact with. 2. **Lead with a headline.** Each entry has a theme name in the `description` field (e.g., "Chat Everywhere", not "v2.28"). The theme should immediately tell users what changed. 3. **One short paragraph** explaining the headline feature — what it does and why it matters. Write for end users, not developers. 4. **3–5 bullets max** for other notable improvements in that release. If you can't fill 3 bullets, roll the changes into the next entry that has a strong headline. 5. **Skip releases without a standout feature.** Not every deploy needs a changelog entry. Only write one when there's something worth headlining. 6. **Casual, clear tone.** Use "you" and "your", not "users". No jargon. No version numbers as headlines.

Format

Create or update `docs/changelog-entries/YYYY-MM-DD.mdx` with frontmatter + markdown:

---
description: "Headline Theme"
---

One or two sentences about the main feature.

- Bullet one
- Bullet two
- Bullet three

The date is derived from the filename automatically.

Do not hand-edit `docs/changelog.mdx`. Regenerate it with `node docs/scripts/build-changelog.mjs`.

What to include

• New features users can try
• Meaningful UX improvements they'll notice
• New platform/integration support

What to skip

• Bug fixes (unless they were widely reported)
• Security hardening (unless there was a public incident)
• Infrastructure, performance, CI/CD changes
• Billing or pricing internals
• Self-hosting or developer-only changes
• Internal refactors, lint fixes, dependency updates

Process

1. Review recent merged PRs: `gh pr list --repo elie222/inbox-zero --state merged --limit 30 --json number,title,mergedAt` 2. Filter to user-facing changes only 3. Group into a theme — find the headline 4. Check for an existing open changelog PR from `automation/changelog` to `main`: `gh pr list --repo elie222/inbox-zero --head automation/changelog --base main --state open --json number,title,url` 5. Create or update today's file `docs/changelog-entries/YYYY-MM-DD.mdx` with frontmatter (`description`) and markdown content 6. If today's file already exists, merge the new updates into that file instead of creating a second entry for the same day 7. Regenerate `docs/changelog.mdx`: `node docs/scripts/build-changelog.mjs` 8. Commit both `docs/changelog-entries/YYYY-MM-DD.mdx` and `docs/changelog.mdx` 9. If the open PR from `automation/changelog` exists, update that branch and PR; otherwise create it from `automation/changelog`

Branch workflow

Before making changes, reset the automation branch to the latest `main` so each run starts from a clean base:

git fetch origin
git checkout -B automation/changelog origin/main

After updating the changelog files, push that branch and create or update the PR from `automation/changelog` to `main`.