From 09413fc7ead6577f7a9b3950c51e8fee1d49d948 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Sat, 26 Sep 2026 04:04:43 +0000 Subject: [PATCH] =?UTF-8?q?=E2=9A=95=EF=B8=8F=EF=BC=9Asay=20where=20change?= =?UTF-8?q?logs=20come=20from?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The contribution guidelines said nothing about changelogs, so the question of whether a project should keep one stayed open, and a contributor had no way to know that the SDK already does, or that its files are generated and not written. They now say so. A project that publishes packages keeps a `CHANGELOG.md` for each, and Changesets writes it at release time from the changeset files pull requests leave in `.changeset/`. A change a package's users would notice adds one, with a summary written for them; a test, refactor, CI or documentation change does not. The section also says why the commit history is not the changelog, and that an entry is corrected in its changeset, since a hand edit to the generated file does not survive the next release. The pull request checklist gains a line pointing at the new section. Signed-off-by: Derek Lewis Assisted-by: Claude-Code:claude-opus-5 Fixes: https://github.com/OpenINF/.github/issues/731 --- CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da339971..9e2298c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -78,6 +78,36 @@ your pull request merged: title of the pull request becomes the subject of the commit that lands — so it answers to the same rules. - [Sign off](#certifying-the-origin-of-your-work) every commit. +- Add a [changeset](#changelogs) when the change is one a package's users will + notice. + +## Changelogs + +A project that publishes packages keeps a `CHANGELOG.md` for each of them, and +nobody writes one by hand. [Changesets][] writes them when a release is cut, +from the changeset files that pull requests leave behind in `.changeset/`. + +So a pull request that changes what a published package does adds a changeset +alongside the code: + +```bash +pnpm exec changeset +``` + +It asks which packages the change touches and how far each version moves, and +the summary it asks for becomes that release's changelog entry. Write the +summary for someone who uses the package, not for a reviewer of the code: +somebody reading a changelog wants to know what is different for them and +whether to act on it. + +A changelog is not the commit history. Commits record how the code got where it +is, for the people who work on it; the changelog records what changed for the +people who depend on it, one release at a time. Changes nobody using the package +would notice, such as tests, refactors, CI and documentation, need no changeset. + +Changesets owns the `CHANGELOG.md` files, so an edit to one made by hand is lost +or misplaced at the next release. To change what a release will say, edit the +changeset before the release is cut. ## License @@ -248,6 +278,7 @@ Please see the [`SECURITY.md`][] file. [`SECURITY.md`]: https://github.com/OpenINF/.github/blob/HEAD/SECURITY.md 'Instructions on how to report security vulnerabilities for this project' +[Changesets]: https://github.com/changesets/changesets [commit-messages]: https://open.inf.is/docs/handbook/style/commit-messages/ [contrib-license]: https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license