From 13cf6b14ab58a8bcaec1bd39b58003f3f51a82cc Mon Sep 17 00:00:00 2001 From: Andrew Shell Date: Mon, 3 Aug 2026 19:00:45 -0500 Subject: [PATCH] ci: keep markdownlint from failing on generated changelogs The Markdown job failed on the first release PR Release Please opened: CHANGELOG.md:12 MD024/no-duplicate-heading [Context: "Changelog"] Two causes, both latent until a release existed. CHANGELOG.md carried a hand-written note under its `# Changelog` heading. Release Please inserts each release directly after that heading, which demoted the note to a `## Changelog` section below the new entry -- colliding with the H1, and sinking further down the file with every future release. The file says not to edit it by hand; the note it carried is already in README.md under "Commits", so drop it and let Release Please own the file outright. That alone would fail again at the second release: MD024 compares every heading in the document, and each release section carries its own `### Bug Fixes`. Scope it to siblings, so headings only collide when they share a parent. Verified by linting a simulated two-release changelog: fails with the current configuration, passes with this one. Co-Authored-By: Claude Opus 5 (1M context) --- .markdownlint-cli2.jsonc | 6 ++++++ CHANGELOG.md | 3 --- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index b4b42e2..3e564e3 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -11,6 +11,12 @@ "no-inline-html": { "allowed_elements": ["br", "img", "kbd"] }, + // A changelog repeats "### Bug Fixes" under every release, which is only a duplicate if the + // whole document is compared at once. Release Please generates those, so the alternative to + // this is a lint failure on every release after the first. + "no-duplicate-heading": { + "siblings_only": true + }, "no-multiple-blanks": { "maximum": 2 }, diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c2d173..825c32f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1 @@ # Changelog - -Maintained by [Release Please](https://github.com/googleapis/release-please) from -[Conventional Commit](https://www.conventionalcommits.org/) subjects on `main`. Do not edit by hand.