| name | creating-changelog |
| description | Use when writing, generating, or updating a vibepit changelog / release notes (e.g. "changelog for v0.3.0", "changelog since v0.2.0", "add a changelog entry"). Covers the docs/changelogs/*.yml format consumed by the release pipeline. |
Creating a Vibepit Changelog
When to Write It
The changelog is normally assembled once, shortly before cutting a release, in a single pass
over the whole commit range since the previous tag (git log --oneline <prev-tag>..HEAD). That way
nothing is forgotten and entries read consistently. git log is the record of what changed, so
there's no need to add an entry for every PR as you go.
Overview
Vibepit changelogs are per-version YAML files at docs/changelogs/{version}.yml.
They are NOT a top-level CHANGELOG.md. At release time, .github/scripts/generate-release-metadata.py
parses the file matching the git tag and renders it into docs/content/releases/{version}.json
and the release notes, turning pr/issue numbers into GitHub links.
Do not create CHANGELOG.md, edit the rendered .json files by hand, or invent the schema —
write one YAML file in docs/changelogs/.
File Format
Filename is the bare version, no v prefix: 0.3.0.yml (matches the release tag v0.3.0).
version: "0.3.0"
added:
- msg: "`allow-cidr` config option to explicitly allow local IP ranges"
pr: "10"
- msg: JetBrains AI service network preset
fixed:
- msg: Preserve formatting in `allow-http`/`allow-dns` appends
pr: "8"
- msg: "`install -m` parameter in the Dockerfile"
version is a quoted string.- Categories, rendered in this fixed order:
added, changed, fixed, deprecated, removed, security. Omit any category with no entries.
- Each entry is a map with a required
msg. Optional pr and issue are quoted strings; the script renders them as (#N) GitHub links — do not put links in msg yourself.
- Quote any
msg that starts with a backtick (otherwise YAML parses it oddly): msg: "extra-hosts config option".
- See
docs/changelogs/TEMPLATE.yml and existing files (0.2.0.yml) for the canonical shape.
Workflow
- Find the range:
git log --oneline <prev-tag>..HEAD (e.g. v0.2.0..HEAD).
- Pick the new version number and name the file
{bare_version}.yml.
- Classify each user-facing commit into a category and write a
msg reworded for users (see below).
- Attach
pr:/issue: when the commit references one ((#11) in the subject, or check git log).
- Within each category, order entries however reads best — existing files trend toward ascending PR number.
Write for Users, Not Developers
The commit subject is written for developers; the changelog msg is read by users who run
vibepit but don't know its internals. Reword anything technical so it describes the
effect on the user, not the code change. Don't just paste the commit subject.
Ask: "What can the user now do / no longer worry about?" Name the user-facing thing (a command,
flag, config key, behavior) and drop internal terms (function names, packages, refactor jargon,
test-infra, "gate", "race", file paths) unless they're genuinely user-visible.
| Commit subject (too technical) | Changelog msg (user-facing) |
|---|
Distinguish forced detaches from clean shell exits | Show a clear message when a session is forcibly detached instead of exiting |
Gate test teardown on full session exit to fix state-file cleanup race | Fix stale session state left behind after disconnecting |
Preserve formatting in allow-http/allow-dns appends | Keep your config file's formatting intact when adding allowlist entries |
Force anonymous auth for cosign image signature verification | Fix image signature verification failing for users not logged in to a registry |
Add allow-cidr config option | Add allow-cidr to explicitly allow access to local IP ranges |
Keep it concise (one line), present-tense, and concrete. If you genuinely can't tell what a
commit means for users, read the PR/diff rather than guessing — or leave it out if it's internal-only.
What to Include / Omit
Changelogs describe user-facing changes, not the commit history. Omit:
- Routine dependency bumps and tooling version updates ("Update dependencies", "Update cosign to X.Y.Z").
- Internal-only commits:
go fmt, lint fixes, test-infra/teardown tweaks, refactors with no behavior change.
- Release-plumbing commits for the previous version (e.g. "generate release metadata for v0.2.0", changelog-formatting fixups) — those belong to the already-shipped release.
Include: new commands/flags/config options, network presets, behavior changes users would notice, bug fixes, security fixes, removals/deprecations, and notable new user-facing docs (how-tos).
Common Mistakes
| Mistake | Fix |
|---|
Creating CHANGELOG.md | Use docs/changelogs/{version}.yml |
Filename v0.3.0.yml | No v prefix: 0.3.0.yml |
Putting (#12) links inside msg | Use the pr: field; the script builds the link |
| Listing dependency bumps / fmt / lint | Omit — not user-facing |
Unquoted msg starting with a backtick | Quote the whole string |
Editing rendered docs/content/releases/*.json | Generated at release; edit the YAML only |
