From 42c2ea9ef7880397f05906fbb709ce840993fcfa Mon Sep 17 00:00:00 2001 From: Paolo Tranquilli Date: Wed, 26 Aug 2026 17:13:12 +0200 Subject: [PATCH] Document merge-commit requirement for release PRs Release, mergeback, and backport PRs must be merged with a merge commit so the branch linkage the release automation depends on is preserved (the mergeback tags the release using the merge commit of the "Merge main into releases/vN" PR, so squashing or rebasing breaks tagging). Add a path-scoped Copilot instructions file scoped to the files that reliably change in these PRs (CHANGELOG.md, src/defaults.json, lib/defaults.json, src/api-compatibility.json), and add an explicit note to the Releasing runbook in CONTRIBUTING.md so the rule is enforced regardless of who merges. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0dae6e42-7fc6-4fb1-b1ea-15dc17e402a2 --- .../instructions/release-merge.instructions.md | 16 ++++++++++++++++ CONTRIBUTING.md | 7 +++++-- 2 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 .github/instructions/release-merge.instructions.md diff --git a/.github/instructions/release-merge.instructions.md b/.github/instructions/release-merge.instructions.md new file mode 100644 index 0000000000..6111917356 --- /dev/null +++ b/.github/instructions/release-merge.instructions.md @@ -0,0 +1,16 @@ +--- +applyTo: "CHANGELOG.md,src/defaults.json,lib/defaults.json,src/api-compatibility.json" +--- + +# Merging release, mergeback, and backport PRs + +The release process creates a cascade of PRs (`main` → `releases/vN`, then +`releases/vN` → `main` mergeback, then `releases/vN` → `releases/v(N-1)` +backport). These PRs reliably touch `CHANGELOG.md`, `src/defaults.json` / +`lib/defaults.json` (bundle/CLI version bump), and `src/api-compatibility.json`. + +Such PRs **must be merged with a merge commit**. Never squash or rebase, as +that breaks the branch linkage the release automation relies on. + +When arming auto-merge on these PRs, use `--merge` (e.g. `gh pr merge --merge`), +not `--squash` or `--rebase`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b67ccb13b7..216097f893 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,10 +60,13 @@ Here are a few things you can do that will increase the likelihood of your pull This workflow goes through the pull requests that have been merged to `main` since the last release, creates a changelog, then opens a pull request to merge the changes since the last release into the `releases/v3` release branch. You can start a release by triggering this workflow via [workflow dispatch](https://github.com/github/codeql-action/actions/workflows/update-release-branch.yml). -1. The workflow run will open a pull request titled "Merge main into releases/v3". Follow the steps on the checklist in the pull request. Once you've checked off all but the last two of these, approve the PR and automerge it. +1. The workflow run will open a pull request titled "Merge main into releases/v3". Follow the steps on the checklist in the pull request. Once you've checked off all but the last two of these, approve the PR and automerge it **with a merge commit** (`gh pr merge --merge`). 1. When the "Merge main into releases/v3" pull request is merged into the `releases/v3` branch, a mergeback pull request to `main` will be automatically created. This mergeback pull request incorporates the changelog updates into `main`, tags the release using the merge commit of the "Merge main into releases/v3" pull request, and bumps the patch version of the CodeQL Action. 1. If a backport to an older major version is required, a pull request targeting that version's branch will also be automatically created. -1. Approve the mergeback and backport pull request (if applicable) and automerge them. +1. Approve the mergeback and backport pull request (if applicable) and automerge them **with a merge commit** (`gh pr merge --merge`). + + > [!NOTE] + > The release, mergeback, and backport pull requests must always be merged with a merge commit — **never squash or rebase**. The mergeback tags the release using the merge commit of the "Merge main into releases/v3" pull request, so squashing or rebasing breaks tagging and the branch linkage the release automation relies on. Once the mergeback and backport pull request have been merged, the release is complete.