Record a change: changelog and docs
Changelog fragment. Run
make changelogand pick the kind:Addedfor something new;Changedfor any behavior an operator or DAG author can notice, even when it fixes a bug: the docs gate readsBreaking,Upgrade,Added,Changed,DeprecatedandRemoved, and a behavior change filed asFixedslips past it;Fixedfor a bug fix that changes nothing else;Security,DeprecatedorRemovedwhen they apply;Breakingfor something that stops working as before, with what users do about it (an intended API break needs it, orChangedorRemoved);Upgradefor what an operator must do before or after upgrading: a migration and how long it takes, a new required setting, a removed flag, with a link to its section of upgrades.
A change can need two fragments: the
Changedentry that says what is different, and theUpgradeentry that says what to do.BreakingandUpgradeentries open the release notes, under Breaking changes and Action required.Highlightsis written for the release, not by each PR (see RELEASING.md).One file per PR in
.changes/unreleased/, so fragments never conflict. A PR with nothing user-facing uses theskip-changeloglabel instead.Docs. Update the pages under
website/content/that describe what you changed: reference for flags, configuration and API, how-to for procedures, upgrades for migrations and new settings. With nothing user-facing, use theskip-docslabel and add a lineSkip-docs: <reason>to the PR description.Milestone. Every PR to
mainnames the release it targets (v0.5.3,v0.6.0); the milestone guard fails without it.Check locally:
bash scripts/check-changelog-entry.sh,bash scripts/check-changelog-structure.shandbash scripts/check-docs-updated.sh, ormake ci-localfor every gate.
What happens to the fragment
You write the fragment; the release tooling does everything else with it.
flowchart LR pr["PR to main<br/>adds .changes/unreleased/x.yaml"] --> cutmain["next cut on main<br/>(patch or minor)<br/>folds x.yaml, deletes it"] pr -. "minor mapped to release-X.Y" .-> pick["cherry-pick -x<br/>to release-X.Y<br/>(same file, same text)"] pick --> cut["patch cut X.Y.Z<br/>folds x.yaml into CHANGELOG.md,<br/>deletes it, dates [X.Y.Z]"] cut --> sync["changelog: sync vX.Y.Z to main<br/>adds [X.Y.Z], deletes x.yaml on main"]
- Do not edit
CHANGELOG.mddated sections (## [X.Y.Z] - <date>). They are published release notes, copied between branches verbatim. - Do not delete or rename a merged fragment yourself. The cut deletes it
when it ships, and after a patch release the sync pull request deletes it
from
main. A fragment renamed or reworded on one side of a cherry-pick is how one entry gets published twice. - When you cherry-pick, keep the fragment exactly as it is on
main(see Backport to a release branch). - The CHANGELOG structure check (
scripts/check-changelog-structure.sh) runs on pull requests that touch the changelog or a fragment. It fails a fragment that does not parse, has a kind.changie.yamldoes not declare or an empty body, or whose text is already an entry of a released section, and aCHANGELOG.mdwhose headings are out of shape or that lacks the section of a tagged release.
The maintainer side (the fold, the dating, the sync and how to recover when it drifts) is in RELEASING.md.