From 6696953d26e8b95eec9a53a3da2b6b4fbe19cf6d Mon Sep 17 00:00:00 2001 From: Myasnikov Daniil Date: Tue, 10 Nov 2026 08:13:30 +0000 Subject: [PATCH] fix(release): set aside the note of a pick that differs from its original A release note describes what the original does on main. A pick git had to fit to a line that already had part of the change, a resolution, or a unit whose first commit came out empty no longer does the same thing, yet its note went into the batch's release-note block with the rest, and the changelog took it from there. A unit now counts as changed when a surviving pick's patch-id differs from its source or the unit's net patch-id differs from the original merge's; the latter catches an empty first commit, which leaves no pick to compare. A changed original's note moves under "Check these notes", fenced and neutralised as before, with a range-diff per differing pick and the two diffs to compare. The range-diff uses a creation factor of 999 because the default leaves a pick that lost most of its change, #5088's test-only pick for one, unpaired. The record and the report list such originals as changed. Assisted-By: LLM Signed-off-by: Myasnikov Daniil --- cmd/backport-batch/README.md | 2 +- cmd/backport-batch/assemble.go | 2 +- cmd/backport-batch/body.go | 41 +++++++++++-- cmd/backport-batch/notes_test.go | 99 +++++++++++++++++++++++++++++++ cmd/backport-batch/record.go | 9 +++ cmd/backport-batch/record_test.go | 2 + cmd/backport-batch/report.go | 20 +++---- cmd/backport-batch/shape.go | 72 +++++++++++++++++----- docs/agents/changelog.md | 2 +- docs/release/backports.md | 2 +- 10 files changed, 217 insertions(+), 34 deletions(-) create mode 100644 cmd/backport-batch/notes_test.go diff --git a/cmd/backport-batch/README.md b/cmd/backport-batch/README.md index 6d9157795..55e04a82c 100644 --- a/cmd/backport-batch/README.md +++ b/cmd/backport-batch/README.md @@ -31,7 +31,7 @@ Build the binary wherever an exit code matters: `go run` turns any non-zero exit Switches the current working tree to `backport-batch/-`, created at `origin/`, and picks onto it one original at a time, in the order they merged into `main`, as one unit each on the branch's first-parent line. A pull request merged into `main` with a merge commit `M` goes on as its own commits, `git rev-list --reverse --topo-order --no-merges M^1..M^2`, each picked with `git cherry-pick -x --signoff`, so each keeps its author, message and sign-offs and gains the `(cherry picked from commit …)` line; the merges that brought `main` into its branch are left out, since `main` already has what they brought. A merge commit then joins the picks to the batch: its first parent is the batch before the original, its second the last pick, and its message is `M`'s with a paragraph of its own, `Backported-from: M`. A pull request squash-merged into `main` goes on as one pick. When any commit of an original conflicts, the pick is aborted, the branch goes back to where it was before that original, and the original is recorded with the commit that failed and its files; the run goes on with the next one. A commit the branch already carries is skipped as empty, and an original none of whose commits changes anything is reported as carried. The tree has to be clean. A local branch of that name is reset to where the run starts; when that drops commits only it has, the run first prints its tip and the `git branch` command that restores them, and so does `--defer`. Signing follows your git configuration; hooks are off for the picks and the merge, so each commit carries its message as git writes it. -The pull request body goes to stdout, built from the line's own `.github/PULL_REQUEST_TEMPLATE.md`: the originals on the branch, each with how many commits it brought and which of them differ from the commit they were picked from by `git patch-id`, a resolution or a pick git had to fit, the deferred conflicts with the commit that failed and its files, the skipped pull requests counted by rule with the lists collapsed, the originals' release notes, and two blocks of JSON: the [line's record](#the-lines-record-and-reports) in `backport-batch`, which later runs, `check` and `notify` act on, and the run's report in `backport-batch-report`. The title is `fix(backport): batch for , `. A body that would pass GitHub's 65536-byte limit leaves out its longest skipped lists, and the run prints them on stderr instead; one that what it has to carry still puts over the limit is refused before anything is pushed. +The pull request body goes to stdout, built from the line's own `.github/PULL_REQUEST_TEMPLATE.md`: the originals on the branch, each with how many commits it brought and which of them differ from the commit they were picked from by `git patch-id`, a resolution or a pick git had to fit, the deferred conflicts with the commit that failed and its files, what is parked and why, the skipped pull requests counted by rule with the lists collapsed, the originals' release notes, and two blocks of JSON. An original whose unit differs from it, a pick whose patch-id differs from its commit's or a unit whose net patch-id differs from the original merge's, as when a first commit came out empty because the line already had that change, keeps its release note out of the release-note block: it goes under "Check these notes", with a `git range-diff --creation-factor=999 ^! ^!` for each pick that differs, which pairs the two however much the pick lost, and the `git diff` of the original's merge and of its unit, and the record and the report mark it `changed`. The two blocks of JSON are the [line's record](#the-lines-record-and-reports) in `backport-batch`, which later runs, `check` and `notify` act on, and the run's report in `backport-batch-report`. The title is `fix(backport): batch for , `. A body that would pass GitHub's 65536-byte limit leaves out its longest skipped lists, and the run prints them on stderr instead; one that what it has to carry still puts over the limit is refused before anything is pushed. `--onto SHA` continues a batch already pushed instead of starting a new one. SHA has to be the head the remote has for a batch branch of the line right now, read with `git ls-remote`, so a head someone pushed onto since is refused. What that branch carries stays, and only what it does not carry yet is picked on top, so the next push is a fast-forward. `--continue` takes SHA from the open batch pull request, and starts a new batch when none is open, which is what the scheduled run does. diff --git a/cmd/backport-batch/assemble.go b/cmd/backport-batch/assemble.go index 53093b018..3162640e2 100644 --- a/cmd/backport-batch/assemble.go +++ b/cmd/backport-batch/assemble.go @@ -408,7 +408,7 @@ func (r *report) lineRecord(doc reportDoc) lineRecord { } slices.SortFunc(dropped, func(a, b droppedEntry) int { return a.Original - b.Original }) return lineRecord{Version: recordVersion, Line: doc.Line, Built: &built, Report: doc.ID, Closing: r.closing, Deferred: slices.Clone(doc.Primary.Deferred), Dropped: dropped, Stale: slices.Clone(doc.Overlays.Stale), - Parked: slices.Clone(doc.Primary.Parked), Partial: slices.Clone(doc.Overlays.Partial)} + Parked: slices.Clone(doc.Primary.Parked), Partial: slices.Clone(doc.Overlays.Partial), Changed: slices.Clone(doc.Overlays.Changed)} } // branchDate is the date a batch branch was opened under. diff --git a/cmd/backport-batch/body.go b/cmd/backport-batch/body.go index 282f93669..998aae924 100644 --- a/cmd/backport-batch/body.go +++ b/cmd/backport-batch/body.go @@ -240,7 +240,7 @@ type report struct { start time.Time // shapes says, for an original on the branch, what it brought, and // partialFiles what a partial unit leaves without effect. - shapes map[*verdict]string + shapes map[*verdict]unitShape partialFiles map[*verdict][]string // missing are originals the policy takes that the run neither tried nor // found anywhere. @@ -306,14 +306,14 @@ func (r *report) ruleTitle(rule int) string { // in details written out. func (r *report) what(details map[int]bool) string { var b strings.Builder - fmt.Fprintf(&b, "Backports to %s from `main`, picked by the rules of the [backport policy](%s) in merge order. A merged pull request comes as its own commits, picked with `git cherry-pick -x` so each keeps its author, message and sign-offs, and a merge commit that carries the original's merge message with a `%s:` trailer naming it; a squash-merged one comes as one pick. `backport-batch verify` checks that shape. A pick listed as changed differs from the commit it came from; `git range-diff ^1..^2 ^1..^2` shows how. A conflict or a failing check here is a [backport task](%sREADME.md).\n\n", codeSpan(r.line.branch()), policyURL, batchTrailer, tasksURL) + fmt.Fprintf(&b, "Backports to %s from `main`, picked by the rules of the [backport policy](%s) in merge order. A merged pull request comes as its own commits, picked with `git cherry-pick -x` so each keeps its author, message and sign-offs, and a merge commit that carries the original's merge message with a `%s:` trailer naming it; a squash-merged one comes as one pick. `backport-batch verify` checks that shape. A pick listed as changed differs from the commit it came from, and its release note waits under Check these notes. A conflict or a failing check here is a [backport task](%sREADME.md).\n\n", codeSpan(r.line.branch()), policyURL, batchTrailer, tasksURL) if len(r.onBranch) == 0 { b.WriteString("Nothing is picked yet.\n") } for _, v := range r.onBranch { shape := "" - if s := r.shapes[v]; s != "" { - shape = ", " + s + if s, ok := r.shapes[v]; ok { + shape = ", " + s.String() } fmt.Fprintf(&b, "- %s %s%s\n", prLink(v.o.number), titleSpan(v.o.title), shape) } @@ -353,6 +353,22 @@ func (r *report) what(details map[int]bool) string { fmt.Fprintf(&b, "- %s %s: %s\n", prLink(p.v.o.number), titleSpan(p.v.o.title), strings.Join(files, ", ")) } } + if changed := r.changed(); len(changed) > 0 { + b.WriteString("\n### Check these notes\n\nThese picks differ from their originals, so their release notes are left out of the release-note block until someone checks that each still holds for this line. Each comes with what to compare: every pick that differs against the commit it came from, and the original's change against the unit's.\n") + for _, v := range changed { + s := r.shapes[v] + fmt.Fprintf(&b, "\n%s %s, carried by %s:\n\n", prLink(v.o.number), titleSpan(v.o.title), codeSpan(s.unit[:12])) + if n := releaseNote(v.o.body); n != "" { + fmt.Fprintf(&b, "```text\n%s\n```\n\n", neutralNote(n)) + } else { + b.WriteString("It has no release note.\n\n") + } + for _, p := range s.pairs { + fmt.Fprintf(&b, "- %s\n", codeSpan(fmt.Sprintf("git range-diff --creation-factor=999 %s^! %s^!", p.source[:12], p.pick[:12]))) + } + fmt.Fprintf(&b, "- %s\n- %s\n", codeSpan(fmt.Sprintf("git diff %s^1 %s", v.o.merge[:12], v.o.merge[:12])), codeSpan(fmt.Sprintf("git diff %s^1 %s", s.unit[:12], s.unit[:12]))) + } + } if len(r.partial) > 0 { fmt.Fprintf(&b, "\n### Still on this branch: only part of it applies\n\nEach of these is on this branch but leaves files of its original as they were on %s, so it carries only part of what it does on `main`. Take each out with `backport-batch run --defer` before the cut; what applies of it goes as a pull request of its own.\n\n", codeSpan(r.line.branch())) for _, v := range r.partial { @@ -454,9 +470,26 @@ func parkReason(p parkedEntry) string { return "builds on " + strings.Join(needs, ", ") + ", which never reaches this line" } +// changed lists the originals on the branch whose unit differs from them, in +// merge order. +func (r *report) changed() []*verdict { + var out []*verdict + for _, v := range r.onBranch { + if s, ok := r.shapes[v]; ok && s.changed() { + out = append(out, v) + } + } + return out +} + +// notes are the release notes of what the branch carries as its originals +// made it; a changed pick's note waits under Check these notes. func (r *report) notes() string { var notes []string for _, v := range r.onBranch { + if s, ok := r.shapes[v]; ok && s.changed() { + continue + } if n := releaseNote(v.o.body); n != "" { notes = append(notes, neutralNote(n)) } diff --git a/cmd/backport-batch/notes_test.go b/cmd/backport-batch/notes_test.go new file mode 100644 index 000000000..35f6ccbb4 --- /dev/null +++ b/cmd/backport-batch/notes_test.go @@ -0,0 +1,99 @@ +/* +Copyright 2026 The Cozystack Authors. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package main + +import ( + "os/exec" + "regexp" + "slices" + "strings" + "testing" +) + +// releaseNoteBlock is the release-note block of a body. +func releaseNoteBlock(t *testing.T, body string) string { + t.Helper() + m := regexp.MustCompile("(?s)```release-note\n(.*?)\n```").FindStringSubmatch(body) + if m == nil { + t.Fatalf("no release-note block in:\n%s", body) + } + return m[1] +} + +// A pick that differs from its original keeps its release note out of the +// release-note block, under Check these notes with what to compare: one git +// had to fit to a line that already had part of the change, and one whose +// first commit came out empty because the line had resized the value itself. +func TestChangedOriginalNoteIsSetApart(t *testing.T) { + f := newFixture(t) + f.squash(2, "chore: a", "", map[string]string{"app/a.txt": appFile}) + f.lines() + f.onLine("release-1.1", "fix(app): two, on the line", map[string]string{"app/a.txt": strings.Replace(appFile, "two", "TWO", 1)}) + f.onLine("release-1.1", "fix(chart): two replicas, on the line", map[string]string{"chart/values.yaml": "replicas: 2\nimage: app:1\n"}) + f.pr(5, "fix(app): two and four", "```release-note\nfix(app): two and four are loud.\n```\n", map[string]string{"app/a.txt": strings.NewReplacer("two", "TWO", "four", "FOUR").Replace(appFile)}) + f.prCommits(6, "fix(chart): two replicas and six", "```release-note\nfix(chart): two replicas by default.\n```\n", + change{files: map[string]string{"chart/values.yaml": "replicas: 2\nimage: app:1\n"}}, + change{files: map[string]string{"app/six.txt": "6\n"}}) + f.pr(7, "fix(app): seven", "```release-note\nfix(app): seven is calm.\n```\n", map[string]string{"app/seven.txt": "7\n"}) + code, stdout, stderr := f.exec(nil, "run", "--line", "release-1.1") + if code != 0 { + t.Fatalf("run = %d\n%s", code, stderr) + } + if got := f.subjects("origin/release-1.1", "HEAD"); !slices.Equal(got, []string{"fix(app): two and four (#5)", "fix(chart): two replicas and six (#6)", "fix(app): seven (#7)"}) { + t.Fatalf("picked %q, want #5, #6 and #7", got) + } + notes := releaseNoteBlock(t, stdout) + if !strings.Contains(notes, "seven is calm") || strings.Contains(notes, "two and four are loud") || strings.Contains(notes, "two replicas by default") { + t.Errorf("the release-note block keeps a changed pick's note, or loses #7's:\n%s", notes) + } + _, check, ok := strings.Cut(stdout, "### Check these notes") + check, _, _ = strings.Cut(check, "\n#") + if !ok || !strings.Contains(check, "two and four are loud") || !strings.Contains(check, "two replicas by default") || strings.Contains(check, "seven is calm") { + t.Errorf("Check these notes does not list #5 and #6 alone:\n%s", stdout) + } + if !strings.Contains(stdout, `"changed":[5,6]`) { + t.Errorf("the record or the report does not mark #5 and #6 changed:\n%s", stdout) + } +} + +// The command printed for a changed pick pairs the pick with the commit it +// came from, however much the pick lost: the default creation factor leaves +// a pick that carries only #5088's test unpaired. +func TestRangeDiffCommandPairsThePick(t *testing.T) { + f, mc5 := policyWorld(t) + gh := &fakeGH{} + head := handBatch(f, gh, mc5) + code, stdout, stderr := f.exec(gh, "run", "--line", "release-1.1", "--continue") + if code != 0 { + t.Fatalf("run --continue = %d\n%s", code, stderr) + } + m := regexp.MustCompile("`git range-diff --creation-factor=999 ([0-9a-f]{12})\\^! ([0-9a-f]{12})\\^!`").FindStringSubmatch(stdout) + if m == nil { + t.Fatalf("the body prints no range-diff for #5's pick:\n%s", stdout) + } + src, pick := f.git("rev-parse", mc5+"^2"), f.git("rev-parse", head+"^2") + if !strings.HasPrefix(src, m[1]) || !strings.HasPrefix(pick, m[2]) { + t.Errorf("the range-diff names %s and %s, want #5's commit %.12s and its pick %.12s", m[1], m[2], src, pick) + } + out, err := exec.Command("git", "range-diff", "--no-color", "--creation-factor=999", m[1]+"^!", m[2]+"^!").Output() + if want := "1: " + f.git("rev-parse", "--short", src) + " ! 1: " + f.git("rev-parse", "--short", pick); err != nil || !strings.HasPrefix(string(out), want) { + t.Errorf("the printed range-diff gives %q, %v; want it to start %q", out, err, want) + } + if out := f.git("range-diff", "--no-color", mc5+"^1.."+mc5+"^2", head+"^1.."+head+"^2"); !strings.Contains(out, " < ") { + t.Errorf("the default creation factor pairs #5's pick after all, so the test shows nothing:\n%s", out) + } +} diff --git a/cmd/backport-batch/record.go b/cmd/backport-batch/record.go index 313279670..81b7626e3 100644 --- a/cmd/backport-batch/record.go +++ b/cmd/backport-batch/record.go @@ -47,6 +47,8 @@ type lineRecord struct { Stale []int `json:"stale"` Parked []parkedEntry `json:"parked,omitempty"` Partial []int `json:"partial,omitempty"` + // Changed are the picks that differ from their originals. + Changed []int `json:"changed,omitempty"` } // recordVersion is the version a run writes. @@ -338,6 +340,13 @@ func (rec *lineRecord) validate(l line) error { } staleSeen[n] = true } + changedSeen := map[int]bool{} + for _, n := range rec.Changed { + if n <= 0 || changedSeen[n] { + return fmt.Errorf("lists %d as a changed pick more than once or not at all", n) + } + changedSeen[n] = true + } partialSeen := map[int]bool{} for _, n := range rec.Partial { // A unit that does only part of its original is still on the batch. diff --git a/cmd/backport-batch/record_test.go b/cmd/backport-batch/record_test.go index ed09d1cd2..d50685edb 100644 --- a/cmd/backport-batch/record_test.go +++ b/cmd/backport-batch/record_test.go @@ -401,6 +401,8 @@ func TestRecordVersion3(t *testing.T) { "an unknown kind": v3(strings.Replace(parked, `"kind":"partial"`, `"kind":"later"`, 1)), "a partial unit not on the batch": v3(strings.Replace(parked, `"partial":[9]`, `"partial":[10]`, 1)), "a partial unit twice": v3(strings.Replace(parked, `"partial":[9]`, `"partial":[9,9]`, 1)), + "a changed pick twice": v3(parked + `,"changed":[4,4]`), + "a changed pick that is none": v3(parked + `,"changed":[0]`), } { if _, err := parseRecord(block(json), l); err == nil { t.Errorf("%s: parseRecord accepted it", name) diff --git a/cmd/backport-batch/report.go b/cmd/backport-batch/report.go index fc6d4dda8..de201fd4a 100644 --- a/cmd/backport-batch/report.go +++ b/cmd/backport-batch/report.go @@ -199,7 +199,7 @@ func buildReport(b *batch, r *report) (reportDoc, error) { } *list = append(*list, numbers(vs)...) } - doc.Overlays = reportOverlays{Dropped: []droppedEntry{}, Stale: numbers(r.stale), Changed: []int{}} + doc.Overlays = reportOverlays{Dropped: []droppedEntry{}, Stale: numbers(r.stale), Changed: numbers(r.changed())} if len(r.partial) > 0 { doc.Overlays.Partial = numbers(r.partial) } @@ -440,15 +440,15 @@ func (d *reportDoc) links() error { return fmt.Errorf("has #%d dropped, but keeps no drop of it", n) } } - // Stale and changed mark something a run took or excluded. - for _, o := range []struct { - name string - list []int - }{{"stale", d.Overlays.Stale}, {"changed", d.Overlays.Changed}} { - for _, n := range o.list { - if c := where[n]; c != "picked" && !strings.HasPrefix(c, "skipped.") { - return fmt.Errorf("marks #%d %s, which it has %s", n, o.name, or(c, "nowhere")) - } + // Stale marks something a run took or excluded, and changed a pick. + for _, n := range d.Overlays.Stale { + if c := where[n]; c != "picked" && !strings.HasPrefix(c, "skipped.") { + return fmt.Errorf("marks #%d stale, which it has %s", n, or(c, "nowhere")) + } + } + for _, n := range d.Overlays.Changed { + if c := where[n]; c != "picked" { + return fmt.Errorf("marks #%d changed, which it has %s", n, or(c, "nowhere")) } } // backport/skip decides before any rule, and backport/include lifts diff --git a/cmd/backport-batch/shape.go b/cmd/backport-batch/shape.go index 3a48d2aa0..ee0a6940d 100644 --- a/cmd/backport-batch/shape.go +++ b/cmd/backport-batch/shape.go @@ -392,15 +392,50 @@ func replayUnit(u unit) (string, []string, error) { return "", nil, err } -// summarize says, for each original the batch head carries in units, how many -// commits it brought and which of them differ from the commit they were picked -// from: a resolution, or a pick git had to fit to the line. -func summarize(b *batch, head string, on []*verdict) (map[*verdict]string, error) { +// pickPair is a pick on the batch and the commit it was picked from. +type pickPair struct{ source, pick string } + +// unitShape is what an original's unit on the batch brought: how many +// commits, the picks that differ from the commit they came from, a +// resolution or a pick git had to fit to the line, and whether the unit as a +// whole makes another change than the original's merge. +type unitShape struct { + unit string + commits int + pairs []pickPair + net bool +} + +// changed says whether the unit differs from its original, so its release +// note may no longer hold. +func (s unitShape) changed() bool { return len(s.pairs) > 0 || s.net } + +// String is the shape as the body lists it. +func (s unitShape) String() string { + out := "1 commit" + if s.commits != 1 { + out = fmt.Sprintf("%d commits", s.commits) + } + if len(s.pairs) > 0 { + var picks []string + for _, p := range s.pairs { + picks = append(picks, codeSpan(p.pick[:12])) + } + out += ", changed in the pick: " + strings.Join(picks, ", ") + } else if s.net { + out += ", changed as a whole: some of its change is not in the picks" + } + return out +} + +// summarize says, for each original the batch head carries in units, what +// its unit brought. +func summarize(b *batch, head string, on []*verdict) (map[*verdict]unitShape, error) { units, err := batchUnits(head, b.lineHead) if err != nil { return nil, err } - out := map[*verdict]string{} + out := map[*verdict]unitShape{} for _, u := range units { v := b.unitOriginal(u) if v == nil || !slices.Contains(on, v) { @@ -414,7 +449,7 @@ func summarize(b *batch, head string, on []*verdict) (map[*verdict]string, error if err != nil { return nil, err } - var changed []string + s := unitShape{unit: u.commit, commits: len(picks)} for _, c := range picks { source := appendedSource(msgs[c].message) if source == "" { @@ -425,16 +460,20 @@ func summarize(b *batch, head string, on []*verdict) (map[*verdict]string, error return nil, err } if !same { - changed = append(changed, codeSpan(c[:12])) + s.pairs = append(s.pairs, pickPair{source: source, pick: c}) } } - s := "1 commit" - if len(picks) != 1 { - s = fmt.Sprintf("%d commits", len(picks)) + // A pick that came out empty leaves no pick to differ, only a net + // change short of the original's. + mine, err := patchIDRange(v.o.merge+"^1", v.o.merge) + if err != nil { + return nil, err } - if len(changed) > 0 { - s += ", changed in the pick: " + strings.Join(changed, ", ") + theirs, err := patchIDRange(u.parents[0], u.commit) + if err != nil { + return nil, err } + s.net = mine != theirs out[v] = s } return out, nil @@ -451,16 +490,17 @@ func plural(n int, word string) string { // parents, by git patch-id of their diffs without context, so that a pick // that only lands among other lines on the line counts as the same. func samePatch(a, b string) (bool, error) { - pa, err := patchID(a) + pa, err := patchIDRange(a+"^", a) if err != nil { return false, err } - pb, err := patchID(b) + pb, err := patchIDRange(b+"^", b) return pa == pb, err } -func patchID(c string) (string, error) { - diff, err := git("diff", "--no-ext-diff", "--no-textconv", "--unified=0", "--end-of-options", c+"^", c) +// patchIDRange is the patch-id of the change from one revision to another. +func patchIDRange(from, to string) (string, error) { + diff, err := git("diff", "--no-ext-diff", "--no-textconv", "--unified=0", "--end-of-options", from, to) if err != nil { return "", err } diff --git a/docs/agents/changelog.md b/docs/agents/changelog.md index 88b86edbd..cfed8704f 100644 --- a/docs/agents/changelog.md +++ b/docs/agents/changelog.md @@ -134,7 +134,7 @@ git log v0.37.1..v0.37.2 --pretty=format:"%h - %s (%an, %ar)" ``` **⚠️ IMPORTANT: Check for backports.** They reach a release line in two shapes: -- A backport batch ([`docs/release/backports.md`](../release/backports.md)): a merge commit titled `fix(backport): batch for release-X.Y, (#BATCH_PR)`. Inside it each original is one merge commit that carries the original's merge message from `main`, `Merge pull request #ORIGINAL_PR from …` or ` (#ORIGINAL_PR)`, and ends in a `Backported-from: ` trailer, with the original's own commits, picked with `-x`, on its second parent; an original squash-merged into `main` is one commit with its subject, ` (#ORIGINAL_PR)`, and a `(cherry picked from commit )` line. Read the original's number, title and author from those, list the batch with `git log --first-parent` inside it, and never write an entry for the batch PR itself or for a picked commit of an original. +- A backport batch ([`docs/release/backports.md`](../release/backports.md)): a merge commit titled `fix(backport): batch for release-X.Y, (#BATCH_PR)`. Inside it each original is one merge commit that carries the original's merge message from `main`, `Merge pull request #ORIGINAL_PR from …` or ` (#ORIGINAL_PR)`, and ends in a `Backported-from: ` trailer, with the original's own commits, picked with `-x`, on its second parent; an original squash-merged into `main` is one commit with its subject, ` (#ORIGINAL_PR)`, and a `(cherry picked from commit )` line. Read the original's number, title and author from those, list the batch with `git log --first-parent` inside it, and never write an entry for the batch PR itself or for a picked commit of an original. An original whose pick differs from it is listed under "Check these notes" in the batch merge's message, which carries the batch PR's body, and in its record's `changed` list: write its entry from what its pick changed on the line, read with the `git range-diff` and `git diff` commands listed there, not from the original's release note. - A single backport PR, from before the batch (the retired label-driven bot) or a release-only fix: commits with "[Backport release-X.Y]" in the message, whose original PR number is in the backport commit message or PR description. - Use the original PR author (not the backport or batch PR author) when creating changelog entries - **MUST** combine the original and backport into a **single entry** with both PR numbers (e.g. `#1606, backport #1609`, where a batch's original reads `#1606, backport #BATCH_PR`). Do NOT list the original and the backport as two separate entries — that produces duplicates in the changelog. diff --git a/docs/release/backports.md b/docs/release/backports.md index bea8ee81f..f76cc3438 100644 --- a/docs/release/backports.md +++ b/docs/release/backports.md @@ -89,7 +89,7 @@ A run by hand trusts the open batch pull request the scheduled run opened as `co `./backport-batch lines` prints the lines, newest first. `run`, `check`, `fold` and `lines` read the policy block from this page on `main`, so until the page with its block is on `main` they need `--policy ` naming a ref that has it, and the scheduled run, which passes none, fails. -`run` picks what the rules take onto `backport-batch/-` and opens a draft pull request against the line. A pull request merged into `main` with a merge commit goes onto the batch as its own commits, oldest first, each picked with `git cherry-pick -x --signoff` so it keeps its author, its message and its sign-offs and gains the sign-off of whoever runs the batch; commits that merged `main` into the pull request's branch are left out. A merge commit joins them to the batch: it carries the original's merge message from `main` and ends in a `Backported-from: ` trailer. A pull request squash-merged into `main` goes on as one pick. When any commit of an original conflicts, nothing of that original stays on the batch. The batch pull request is merged into the line with a merge commit, so all of this reaches the line as it is. Its body lists the originals with how many commits each brought and which of them differ from the commit they came from, the conflicts it deferred with the commit that failed and its files, what it parked and why, and what it skipped under which rule, and ends with the [line's record and the run's report](#the-lines-record-and-reports); `--push` prints the pull request's URL. While that pull request is open, the next run continues it, `--continue` reading its head, rather than opening another. CI on the batch pull request runs the line's build and tests, and a maintainer merges it. Since rule 6 reads the newer line itself, an older line takes a fix in the batch after the newer line's batch with that fix has merged. +`run` picks what the rules take onto `backport-batch/-` and opens a draft pull request against the line. A pull request merged into `main` with a merge commit goes onto the batch as its own commits, oldest first, each picked with `git cherry-pick -x --signoff` so it keeps its author, its message and its sign-offs and gains the sign-off of whoever runs the batch; commits that merged `main` into the pull request's branch are left out. A merge commit joins them to the batch: it carries the original's merge message from `main` and ends in a `Backported-from: ` trailer. A pull request squash-merged into `main` goes on as one pick. When any commit of an original conflicts, nothing of that original stays on the batch. The batch pull request is merged into the line with a merge commit, so all of this reaches the line as it is. Its body lists the originals with how many commits each brought and which of them differ from the commit they came from, whose release notes wait under "Check these notes" with what to compare, since a note may not hold for a pick that differs, the conflicts it deferred with the commit that failed and its files, what it parked and why, and what it skipped under which rule, and ends with the [line's record and the run's report](#the-lines-record-and-reports); `--push` prints the pull request's URL. While that pull request is open, the next run continues it, `--continue` reading its head, rather than opening another. CI on the batch pull request runs the line's build and tests, and a maintainer merges it. Since rule 6 reads the newer line itself, an older line takes a fix in the batch after the newer line's batch with that fix has merged. A deferred conflict waits for the next batch. To land it sooner, pick the original's commits onto the batch head with `git cherry-pick -x`, resolving each conflict, and join them to the batch head with a merge commit that names the original; an original squash-merged into `main` is one pick of its commit there, with no merge. Check that merge or that pick with `./backport-batch fold --line --original --commit `, and push it onto the batch branch, as [resolving a conflict](./backport-tasks/resolve-conflict.md) describes. CI runs `backport-batch verify` on every push to a batch pull request, which holds every original on it to the same shape. When CI on the batch pull request fails, the original it comes from is taken out with `./backport-batch run --line --defer --reason --push` and goes to the next batch, as [attributing a failed batch CI](./backport-tasks/failed-ci.md) describes; the rest of the batch merges without it. When it is all the batch carries, `--push` records why in the batch pull request, closes it and deletes its branch, and the next batch tries it again. `--drop` and `--undrop` change the record of the open batch pull request in the same way, and need one.