From bf91765349b9074545546dcae85289f6285c539f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Houpert?=
 <10154151+lhoupert@users.noreply.github.com>
Date: Tue, 10 Nov 2026 13:36:28 +0000
Subject: [PATCH] chore: explain how CHANGES.md works with release-please

Breaking changes noted only in CHANGES.md made release-please propose a patch release.
---
 CONTRIBUTING.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9126c45c..b1383c1d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -45,4 +45,6 @@ Releases are automated with [release-please](https://github.com/googleapis/relea
 
 - `fix:`, `perf:`, `deps:`, `revert:` and `docs:` lead to a patch release, `feat:` to a minor one, and a breaking change (`feat!:` or a `BREAKING CHANGE:` footer) to a major one.
 - `chore:`, `ci:`, `test:`, `build:`, `refactor:` and `style:` don't trigger a release on their own.
-- release-please keeps a release PR open with the next version; merging it tags the release and publishes it. CHANGES.md is still written by hand.
+- release-please keeps a release PR open with the next version; merging it tags the release and publishes it.
+- CHANGES.md is written by hand: add your change under `## [unreleased]`. For a breaking change, also mark the commit with `!` (e.g. `feat!:`), otherwise the release gets a patch or minor version.
+- At release time, a maintainer adds the `## [X.Y.Z] - date` heading under `## [unreleased]` and updates the links at the bottom of CHANGES.md. If the version should differ from the one release-please proposes, that commit also ends with a `Release-As: X.Y.Z` line.