From e36aede6cc0d415ced0934743fe6e7b11701fa50 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 14:42:17 -0800 Subject: [PATCH] docs: allow bench-only backports to release `release` could only take a release cut or a fix backport, so a benchmark added on `main` could not join a pairing against `release` until the next cut. Allow bench-only backports: benchmarks and their harness, with no shipped code changed. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- CONTRIBUTING.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 2ca01aa1b6a..b0fd87c1b2c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,7 +82,7 @@ The boundary between packages is extremely important to keep things modular and # Development PRs target `main`, the trunk, where breaking API changes are allowed. -`release` is what ships; touch it only to cut a release or backport a fix (see `CONTRIBUTING.md`). +`release` is what ships; touch it only to cut a release, backport a fix, or backport benchmarks (see `CONTRIBUTING.md`). Wire changes should be backwards compatible for any *published* drafts/versions. Between our own builds only moq-lite compatibility is guarded, since our implementations always prefer it; moq-transport compatibility matters against third-party implementations. An unpublished `-wip` version changes freely, so never defer a better wire design to keep it compatible. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 174f45da228..85057449c61 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,6 +95,7 @@ For an advisory against Quinn, follow the advisory triage in [`rs/moq-quic/READM - A release is cut by hand: a PR merging `main` into `release`, with a merge commit. - A breaking cut first writes, on `main`, each changed package's version-transition section in its `MIGRATE.md` (`## 0.3 -> 0.4`) from the migration audit: the `!` subjects since the `release` merge base, each of those PRs' Impact section, and the API diff. - Suggest a `release` backport for any serious bug fix (crash, security, data loss, broken interop), whether found on `main` or reported against a release. Land it on `main` first, then port it onto `release` as a separate PR that keeps the published API, so it ships as a patch. The Release gate's API diff (`just api-diff --deny`) fails a backport that changes one; on the cut PR, whose head is `main`, it only reports. +- A bench-only backport ports `main`'s benchmarks onto `release`, so a pairing against `release` (`just bench origin/release`) compares them. It carries only benchmarks and their harness: bench targets, bench-only dev-dependencies, and `bench/`. It changes no shipped code, and it shims locally any API that `release` lacks, keeping each case's ID the same as on `main`. A case that measures code `release` doesn't have is left out, and the PR lists it. Merging one makes release-plz propose patch bumps for the crates it touches, though no shipped code changed. - After any release publishes, patch or breaking, run `just test wire-compat --remeasure` on `main` and land the rewritten `test/interop/compat/planned-breaks.json` with refreshed reasons. Otherwise the nightly wire-compat check fails on the stale pins. - Nothing merges `release` into `main` automatically. Before cutting a minor or breaking release, the maintainer merges `release` into `main` once, so trunk carries the published versions, CHANGELOGs, and any `release`-only commits. It lands as a merge commit with `--admin`, never squashed, so the cut starts from an advanced merge base.