Skip to content

docs(changelog): a pull request leaves CHANGELOG.md alone; the release step writes it - #23

Merged
jmineau merged 1 commit into
mainfrom
docs/changelog-at-release
Oct 26, 2026
Merged

jmineau merged 1 commit into
mainfrom
docs/changelog-at-release

Conversation

@jmineau

@jmineau jmineau commented Oct 26, 2026

Copy link
Copy Markdown
Owner

Summary

A pull request no longer touches CHANGELOG.md. At release the maintainer runs just changelog (git-cliff, already in the template) and edits its output into the file before tagging. This is the maintainer's decision "CHANGELOG at release, not in each PR" (no issue exists).

Why: every PR that adds a line under ## [Unreleased] is the usual rebase conflict between open PRs in one package, and the entry is written from the commit messages at release either way.

What changes in a generated project:

  • AGENTS.md: the "Commits, changelog, releases" bullet says a PR leaves CHANGELOG.md alone and the entries are drafted at release; the commit message is the line a user will read. The command table says just changelog is for release.
  • CONTRIBUTING.md: the "add a line under ## [Unreleased]" step is gone (the steps are renumbered; the commit step says to leave CHANGELOG.md alone). The "Releasing" step 1 now opens "Write the changelog", with the same just changelog and rename-the-heading steps as before. The recipe table says "run at release".
  • PR template: the CHANGELOG.md checkbox is removed.
  • CHANGELOG.md: one sentence in the intro says PRs leave it alone and the entries are written at release.
  • justfile comment on the changelog recipe says "At release".
  • Template README.md: the Changelog row says the same.

Not changed: the ## [Unreleased] heading in CHANGELOG.md and the release steps that rename it. Dropping the heading would conflict in every package's CHANGELOG.md at copier update (each has its own entries under it); keeping it applies cleanly. cliff.toml, just release and the Publish workflow are untouched.

Rollout (after a template release is tagged)

Each package: copier update, then delete the line "User-visible changes go under ## [Unreleased]" from its own AGENTS.md. The maintainer's own brief for agents (kept outside this repo) drops its CHANGELOG instruction at the same time. This PR touches no package and tags nothing.

Checks

  • just test (bakes both variants, publish_to_pypi and docs_notebooks yes and no; quality-check, docs build, pre-commit hooks, dist, version checks, and the just changelog draft check) in a Slurm job: passed for both variants (every hook, the docs build with its examples, the dist build, the version checks and the just changelog draft).
  • Read the baked AGENTS.md, CONTRIBUTING.md, CHANGELOG.md and the PR template: the text reads as above and nothing says to add a line under ## [Unreleased] in a PR.
  • Not checked: that a package's copier update applies this cleanly (done per package after the release).

@jmineau
jmineau merged commit 0cac4d3 into main Oct 26, 2026
1 check passed
@jmineau
jmineau deleted the docs/changelog-at-release branch October 26, 2026 17:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant