From bda230c19d5b93fbb0e25962023cc1ff28831f4c Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Fri, 31 Jul 2026 18:50:42 +0200 Subject: [PATCH] Seed the changelog backports scaffold when cutting a stable branch A stable branch's changelog needs the `# v{next} backports` heading (with `## In this release` / `## In previous releases`) plus a `# v{this} changes` wrapper so backported PRs have a place to land and the monthly patch release has entries to demote. The current stable v1.10 branch was cut without that scaffold, so a backport had nowhere correct to go and risked being mis-filed under the frozen `## Regression fixes` (which tracks the previous version's own release fixes, not backports). Add the seed step to the branch-creation checklist, and make the backport checklist, the stable patch-release checklist, and the changelog rule all reference the scaffold explicitly so the section names stay consistent across docs. --- .claude/rules/changelog.md | 4 +++- dev-docs/checklist-backport-a-pr.md | 5 +++-- dev-docs/checklist-make-a-new-quarto-release.md | 1 + dev-docs/checklist-make-a-new-stable-quarto-release.md | 2 +- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/.claude/rules/changelog.md b/.claude/rules/changelog.md index e94b85e7ae8..2784b3e90da 100644 --- a/.claude/rules/changelog.md +++ b/.claude/rules/changelog.md @@ -107,7 +107,9 @@ The stable changelog has a dual top-level structure that does NOT exist on main: **Backport entries always go under `# v{next} backports > ## In this release`.** Never under `## Regression fixes` of the `# v{this} changes` section — that section is frozen and tracks the original v1.x release. -**Lifecycle:** When the next v1.x.y patch ships, entries under `## In this release` get demoted to `## In previous releases` as part of release prep. Don't pre-empt this — leave them under `In this release` until release time. +**Where the scaffold comes from:** the `# v{next} backports` heading (with empty `## In this release` / `## In previous releases`) and the `# v{this} changes` wrapper are seeded when the stable branch is cut — see the branch-creation step in `dev-docs/checklist-make-a-new-quarto-release.md`. If a stable branch is missing the `# v{next} backports` heading, it was cut without it: add the scaffold before filing the entry, rather than falling back to `## Regression fixes`. + +**Lifecycle:** When the next v1.x.y patch ships, entries under `## In this release` get demoted to `## In previous releases` as part of release prep (the changelog step in `dev-docs/checklist-make-a-new-stable-quarto-release.md`). Don't pre-empt this — leave them under `In this release` until release time. ### Workflow diff --git a/dev-docs/checklist-backport-a-pr.md b/dev-docs/checklist-backport-a-pr.md index 685ca968e15..be00ac1141b 100644 --- a/dev-docs/checklist-backport-a-pr.md +++ b/dev-docs/checklist-backport-a-pr.md @@ -5,7 +5,8 @@ We backport development PRs to the stable branch using the following steps: - Cherry-pick the commits from the development branch: - `git cherry-pick ` for every commit identified above. - Resolve conflicts as needed. -- Revert the changelog file changes if it was included in the original commits. -- Move the new changelog entries to the top of old changelog, under "New in this release". +- Revert the changelog file changes if they were included in the original commits (the dev-branch `changelog-1.(x+1).md` does not exist on the stable branch, so the cherry-pick shows a modify/delete conflict — drop that hunk). +- Add the new changelog entries to `news/changelog-1.x.md`, under `# v1.(x+1) backports` > `## In this release` at the top of the file. There are change categories in the development release but not in the backport release, so just add them chronologically to the section. + If that scaffold heading is missing, the stable branch was cut without it — seed it per the branch-creation step in `checklist-make-a-new-quarto-release.md` rather than filing the entry under the frozen `## Regression fixes` (that section is the previous version's own release fixes). - Run the test suite GHA workflow on the stable branch manually. diff --git a/dev-docs/checklist-make-a-new-quarto-release.md b/dev-docs/checklist-make-a-new-quarto-release.md index 3fc6235136c..6765f6c1e61 100644 --- a/dev-docs/checklist-make-a-new-quarto-release.md +++ b/dev-docs/checklist-make-a-new-quarto-release.md @@ -8,6 +8,7 @@ - `git checkout -b v1.4` - `git push origin v1.4` - [ ] on this new branch, set `CITATION.cff` `version` (quote it — e.g. `"1.4"`; unquoted `1.10`-style values parse as a YAML float and lose the trailing zero) and `date-released` (today), then commit and push. Set once per branch here; the `CITATION.cff` step on `main` below is a cherry-pick of this commit, not a re-edit. + - [ ] on this new branch, seed the backports scaffold in `news/changelog-1.x.md`: wrap the existing body under a `# v1.x changes` heading and prepend a `# v1.(x+1) backports` heading holding empty `## In this release` and `## In previous releases` subsections (e.g. cutting `v1.4` with `main` moving to `1.5`, prepend `# v1.5 backports`). Commit and push. Backported PRs land under `## In this release` (`checklist-backport-a-pr.md`); the monthly patch release demotes them to `## In previous releases` (`checklist-make-a-new-stable-quarto-release.md`). Without this scaffold later backports have nowhere correct to go and get mis-filed under the frozen `## Regression fixes`. - [ ] mark the current release as the new release in the `main` branch - [ ] switch your repo back to `main`: `git checkout main` - [ ] edit the QUARTO_VERSION line in `/configuration` to the new version (e.g. `1.5`) diff --git a/dev-docs/checklist-make-a-new-stable-quarto-release.md b/dev-docs/checklist-make-a-new-stable-quarto-release.md index aecd2faf9dc..276483fcfef 100644 --- a/dev-docs/checklist-make-a-new-stable-quarto-release.md +++ b/dev-docs/checklist-make-a-new-stable-quarto-release.md @@ -36,7 +36,7 @@ - Got to - In the "Build Choco package & Publish" workflow, click "Run Workflow" and be sure to check the "Whether to publish or not the package on chocolatey" checkbox - Wait for @cderv to receive email confirmation, no action needed. -- [ ] Update the stable changelog by moving entries to the "in previous release". Use "[release checklist]" in the commit message to make it easier to spot if a new release is needed next month. +- [ ] Update the stable changelog `news/changelog-1.x.md` by moving entries from `# v1.(x+1) backports` > `## In this release` down to `## In previous releases` — they've now shipped in this patch. Use "[release checklist]" in the commit message to make it easier to spot if a new release is needed next month. - Others installers - Cloudsmith: Automatically published by Build Installers workflow. No action needed.