Skip to content

Commit 2b53cf9

Browse files
fix(release): resolve backport targets the way the freeze contract does
backport.yaml stopped resolving its target branches from getLatestRelease in 6ff5b98: it now lists the repository's branches, keeps release-X.Y, and takes the two newest by version. The audit still reproduced the old rule, so it was correct only outside a freeze window -- and a freeze window is the whole point, because release-X.Y is created when the first vX.Y.0-rc.N is cut, potentially weeks before vX.Y.0 publishes, and the frozen branch is the only way into that release. At the next rc cut the audit would have started attributing every kind/backport PR to the line behind the one it was written for: false MISSING on the old line, and silence on the new one. Carry both rules and pick by the PR's merge date. A single cutover is faithful because both halves landed in the same push -- 53a7fc4 made cutting an rc freeze the line, 6ff5b98 pointed the bot at the branch list -- and before it a release branch was created at promote time, so the newest branch and the newest published stable named the same line and the two rules could not disagree. The branch-push moment is read exactly rather than approximated, from the committer date of the commit the first vX.Y.0-rc.N tag points at. cut-prerelease.yaml creates the branch AT that commit, in the same job and immediately after the tag push, and the stale-tip guard just above that push refuses to proceed unless the commit is still main's tip. So nothing merges to main in between: every PR merged after that commit merged after the branch existed, and every PR merged before it merged before. There is no window for the two to disagree. The rc release's publishedAt could not offer that -- it lands hours later, once tags.yaml has finished building. Rank the live lines by version rather than by when they opened, which is the sort backport.yaml applies to its own branch list. The two orders come apart as soon as a freeze overlaps the previous line's stabilisation, and version order is also what keeps release-1.10 above release-1.9. Verified two ways. Output is byte-identical over 98 verdicts across release-1.6, release-1.5 and release-1.4, which is the expected result rather than a weak one: no line has been frozen since the cutover, so no verdict may move yet. Moving the cutover back so that v1.6.0-rc.1 counts as a freeze then shifts exactly the 12 PRs merged inside 1.6's real freeze window from release-1.5 to release-1.6, and every one of them lands in-branch there -- they merged to main before that branch was cut, which is what the enumeration rule says and what the published-stable rule missed. main_test.go pins the rule itself and `make unit-tests` now runs it. The mapping is stated in this repo but enforced by backport.yaml and cut-prerelease.yaml, so a change there that is not mirrored here turns a release gate silently permissive, which is the one failure mode a gate must not have. Assisted-By: Claude <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
1 parent 45523d7 commit 2b53cf9

5 files changed

Lines changed: 330 additions & 23 deletions

File tree

‎Makefile‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: manifests assets unit-tests helm-unit-tests bats-unit-tests rd-presets-check migrations-target-check test test-controllers preflight
1+
.PHONY: manifests assets unit-tests helm-unit-tests bats-unit-tests rd-presets-check migrations-target-check test test-controllers test-backport-audit preflight
22

33
include hack/common-envs.mk
44

@@ -106,7 +106,7 @@ test:
106106
make -C packages/core/testing apply
107107
make -C packages/core/testing e2e
108108

109-
unit-tests: helm-unit-tests bats-unit-tests go-unit-tests rd-presets-check test-check-readiness migrations-target-check
109+
unit-tests: helm-unit-tests bats-unit-tests go-unit-tests rd-presets-check test-check-readiness test-backport-audit migrations-target-check
110110

111111
helm-unit-tests:
112112
hack/helm-unit-tests.sh
@@ -149,6 +149,16 @@ test-controllers:
149149
test-check-readiness:
150150
go test ./test/check-readiness/ -count=1
151151

152+
# Unit tests for cmd/backport-audit, named individually for the same reason
153+
# test-check-readiness is: ./cmd/... as a whole stays out of go-unit-tests.
154+
# What they pin is the rule that maps a backport label to a release branch,
155+
# which lives in this repo but is enforced by .github/workflows/backport.yaml
156+
# and .github/workflows/cut-prerelease.yaml. A change to either that is not
157+
# mirrored here turns the pre-release audit silently permissive, which is the
158+
# one failure mode a release gate must not have.
159+
test-backport-audit:
160+
go test ./cmd/backport-audit/ -count=1
161+
152162
# Discover every hack/*.bats file that is NOT an e2e test and run it
153163
# through cozytest.sh. Drop a new *.bats file in hack/ and it is picked
154164
# up automatically on the next `make unit-tests` run.

‎cmd/backport-audit/README.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,13 +61,22 @@ go run ./cmd/backport-audit release-1.5 || echo "do not cut yet"
6161

6262
## How a PR is matched to a release line
6363

64-
A `kind/backport` label does not name a branch. [`backport.yaml`](../../.github/workflows/backport.yaml) resolves the target from `getLatestRelease` **at merge time**, so the same label means `release-1.5` on a PR merged in June and `release-1.6` on one merged in August.
64+
A `kind/backport` label does not name a branch. [`backport.yaml`](../../.github/workflows/backport.yaml) resolves the target **at merge time**, so the same label means `release-1.5` on a PR merged in June and `release-1.6` on one merged in August. The audit reproduces that rule rather than trusting the label text: a PR is a candidate for `release-X.Y` when it merged carrying `kind/backport` while `X.Y` was the current line, or `kind/backport-previous` while `X.Y` was one minor behind. Without this, auditing an older line reports every newer-era PR as missing.
6565

66-
The audit reproduces that rule rather than trusting the label text: a PR is a candidate for `release-X.Y` when it merged carrying `kind/backport` while `X.Y` was the current line, or `kind/backport-previous` while `X.Y` was one minor behind. A line is treated as current from the publication of its first non-prerelease release, which is what `getLatestRelease` returns. Without this, auditing an older line reports every newer-era `kind/backport` PR as missing.
66+
What "the current line" means changed once, so the audit carries both rules and picks by the PR's merge date:
6767

68-
The labels were namespaced under `kind/` in 7b71053a0, which renamed them in place via label-sync aliases, so every historical PR reads back under the new name. The bare `backport` and `backport-previous` are still queried alongside them, because the org-level dosubot goes on applying the old spelling to new PRs — the same transitional allowance [`backport.yaml`](../../.github/workflows/backport.yaml) makes, and it retires at the same time. A PR found under either spelling is reported under the `kind/` one.
68+
| PR merged | rule `backport.yaml` was running | a line exists from |
69+
|-----------|----------------------------------|--------------------|
70+
| before 2026-08-03 | `getLatestRelease` | its first non-prerelease release publishing |
71+
| on or after 2026-08-03 | the two newest existing `release-X.Y` branches | its `release-X.Y` branch being pushed |
6972

70-
One divergence is open and deliberate. `backport.yaml` stopped calling `getLatestRelease` in 6ff5b98d5 and now takes the two newest existing `release-X.Y` branches, which opens a line at its first rc rather than at its first stable. The two rules agree outside a freeze window, and no window has opened since that commit, so every PR audited so far merged under the rule reproduced here — the next rc cut is what makes them disagree.
73+
The cutover is a single moment because both halves landed in one push: 53a7fc4dc made cutting an rc freeze the line into `release-X.Y`, and 6ff5b98d5 pointed the bot at the branch list. Before that a release branch was created at promote time, so the newest branch and the newest published stable named the same line and the two rules could not disagree. After it they disagree for the length of every freeze window — `release-X.Y` is created when the first `vX.Y.0-rc.N` is cut, potentially weeks before `vX.Y.0` publishes, and everything labelled in between belongs to the line being stabilised. That window is exactly when a backport has to reach the branch, because the frozen branch is the only way into the release.
74+
75+
The branch-push moment is read exactly rather than approximated. [`cut-prerelease.yaml`](../../.github/workflows/cut-prerelease.yaml) creates the branch **at the tagged commit**, in the same job and immediately after the tag push, and the stale-tip guard just above that push refuses to proceed unless the dispatched commit is still `main`'s tip. So nothing merges to `main` between the tagged commit and the branch appearing, and that commit's own date splits every PR correctly: merged before it, the branch did not exist; merged after it, it did. The rc release's `publishedAt` would not do, since it lands hours later once `tags.yaml` has finished building.
76+
77+
Lines are then ranked by version and never by when they opened, matching the numeric descending sort the workflow applies to its branch list. The two orders come apart as soon as a freeze overlaps the previous line's stabilisation, and version order is also what keeps `release-1.10` above `release-1.9`.
78+
79+
The labels themselves were namespaced under `kind/` in 7b71053a0, which renamed them in place via label-sync aliases, so every historical PR reads back under the new name. The bare `backport` and `backport-previous` are still queried alongside them, because the org-level dosubot goes on applying the old spelling to new PRs — the same transitional allowance [`backport.yaml`](../../.github/workflows/backport.yaml) makes, and it retires at the same time. A PR found under either spelling is reported under the `kind/` one.
7180

7281
## How landing is established
7382

‎cmd/backport-audit/main.go‎

Lines changed: 115 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,10 @@ limitations under the License.
2323
// `kind/backport` label while X.Y was the current release line, or the
2424
// `kind/backport-previous` label while X.Y was one minor behind it. That
2525
// mirrors .github/workflows/backport.yaml, which resolves its target branches
26-
// from the latest published release at merge time rather than from the label
27-
// itself, so the same label means a different branch depending on when the PR
28-
// merged.
26+
// at merge time rather than from the label itself, so the same label means a
27+
// different branch depending on when the PR merged. What "the current line"
28+
// meant changed once, at the freeze contract; lineOpenDates carries both
29+
// rules and the reason a single cutover reproduces them faithfully.
2930
//
3031
// Landing is established from three independent kinds of evidence: the PR's
3132
// merge commit already being reachable from the release branch (it merged
@@ -81,8 +82,25 @@ var (
8182
backportBodyRE = regexp.MustCompile(`[Bb]ackport of\s+(?:[\w.-]+/[\w.-]+)?#(\d+)`)
8283
cherryPickRE = regexp.MustCompile(`cherry picked from commit ([0-9a-f]{7,40})`)
8384
releaseTagRE = regexp.MustCompile(`^v(\d+)\.(\d+)\.(\d+)$`)
85+
// The tag whose cut creates release-X.Y. cut-prerelease.yaml gates the
86+
// freeze on kind == rc and patch == 0, so alpha, beta and patch-line rcs
87+
// deliberately do not match.
88+
freezeTagRE = regexp.MustCompile(`^v(\d+)\.(\d+)\.0-rc\.\d+$`)
8489
)
8590

91+
// freezeContractLandedAt is when cutting an rc started creating release-X.Y,
92+
// and with it when backport.yaml stopped resolving its targets from the last
93+
// published stable.
94+
//
95+
// One moment, not two: 53a7fc4dc ("cutting an rc freezes the line into
96+
// release-X.Y") and 6ff5b98d5 ("target the newest existing release line")
97+
// landed on main in the same push, which is what makes a single cutover
98+
// faithful. Before it a release-X.Y branch was created at promote time, so the
99+
// newest branch and the newest published stable named the same line and the
100+
// two rules could not disagree. After it they disagree for the length of every
101+
// freeze window, which is precisely when a backport has to reach the branch.
102+
var freezeContractLandedAt = time.Date(2026, 8, 3, 16, 31, 59, 0, time.UTC)
103+
86104
// The two backport requests .github/workflows/backport.yaml acts on, named by
87105
// the label that carries them. These names are what the audit reports.
88106
const (
@@ -444,18 +462,26 @@ type lineOpen struct {
444462
when time.Time
445463
}
446464

447-
// lineOpenDates reports when each release line became the current one, oldest
448-
// first. A line opens when its first non-prerelease release is published,
449-
// which is when getLatestRelease in backport.yaml starts resolving
450-
// `kind/backport` to that line. Drafts and prereleases are skipped, as that
451-
// API does.
465+
// lineOpenDates reports when each release line came into existence as a
466+
// backport target, oldest first, reproducing whichever rule backport.yaml was
467+
// running at the time.
468+
//
469+
// Since freezeContractLandedAt a line exists from the moment its release-X.Y
470+
// branch is pushed, which is what the workflow's branch enumeration sees; see
471+
// freezeDates for how that moment is read exactly. Before it, a line existed
472+
// from the publication of its first non-prerelease release, which is what
473+
// getLatestRelease returned; drafts and prereleases are skipped, as that API
474+
// does.
452475
//
453-
// backport.yaml stopped calling getLatestRelease in 6ff5b98d5 and now takes the
454-
// two newest existing release-X.Y branches instead, which opens a line at its
455-
// first rc rather than at its first stable. The two rules agree everywhere
456-
// except inside a freeze window, and no window has opened since that commit
457-
// landed, so every PR audited so far merged under the rule reproduced here.
458-
// The next rc cut is what makes them diverge.
476+
// The two are combined per line rather than by era, because a PR merged after
477+
// the cutover is judged against every branch that exists by then, including
478+
// the ones created long before it. That is sound in both directions: a line
479+
// created under the freeze contract cannot predate the cutover, and a line
480+
// created before it had a branch well before the enumeration rule ever ran, so
481+
// which of the two dates is used for an old line cannot change a verdict.
482+
// release-1.4 is the case that proves it — its branch was cut at v1.4.0-rc.2,
483+
// five days before v1.4.0 published — and both dates sit months on the far
484+
// side of the cutover.
459485
func lineOpenDates() ([]lineOpen, error) {
460486
var releases []struct {
461487
TagName string `json:"tagName"`
@@ -485,6 +511,14 @@ func lineOpenDates() ([]lineOpen, error) {
485511
}
486512
}
487513

514+
frozen, err := freezeDates()
515+
if err != nil {
516+
return nil, err
517+
}
518+
for l, when := range frozen {
519+
earliest[l] = when
520+
}
521+
488522
opened := make([]lineOpen, 0, len(earliest))
489523
for l, when := range earliest {
490524
opened = append(opened, lineOpen{l, when})
@@ -493,20 +527,85 @@ func lineOpenDates() ([]lineOpen, error) {
493527
return opened, nil
494528
}
495529

530+
// freezeDates reports, for each line whose release-X.Y branch was created by
531+
// the freeze, the exact moment it started existing.
532+
//
533+
// The moment is read as the committer date of the commit the first
534+
// vX.Y.0-rc.N tag points at, which is exact rather than approximate. The
535+
// freeze creates the branch AT the tagged commit, in the same job and
536+
// immediately after the tag push, and the stale-tip guard just above that push
537+
// refuses to proceed unless the dispatched commit is still main's tip. So
538+
// nothing merges to main between the tagged commit and the branch appearing:
539+
// every PR merged after that commit merged after the branch existed, and every
540+
// PR merged before it merged before. There is no window for the two to
541+
// disagree, which the rc release's publishedAt could not offer -- that lands
542+
// hours later, once tags.yaml has finished building.
543+
//
544+
// Lines whose first such tag predates the cutover are dropped: their branches
545+
// were not created by the freeze, so the tag says nothing about when they
546+
// appeared, and lineOpenDates falls back to the published-stable rule that was
547+
// actually in force for them.
548+
func freezeDates() (map[line]time.Time, error) {
549+
out, err := git("for-each-ref", "--format=%(refname:strip=2) %(committerdate:iso-strict)", "refs/tags/v*")
550+
if err != nil {
551+
return nil, err
552+
}
553+
return parseFreezeDates(out)
554+
}
555+
556+
// parseFreezeDates is the half of freezeDates that does not need a repository:
557+
// `<tag> <iso-8601 date>` per line, in, freeze moments out.
558+
func parseFreezeDates(out string) (map[line]time.Time, error) {
559+
frozen := map[line]time.Time{}
560+
for raw := range strings.SplitSeq(out, "\n") {
561+
name, date, ok := strings.Cut(strings.TrimSpace(raw), " ")
562+
if !ok {
563+
continue
564+
}
565+
m := freezeTagRE.FindStringSubmatch(name)
566+
if m == nil {
567+
continue
568+
}
569+
when, err := time.Parse(time.RFC3339, date)
570+
if err != nil {
571+
return nil, fmt.Errorf("tag %s: unparseable date %q: %w", name, date, err)
572+
}
573+
if when.Before(freezeContractLandedAt) {
574+
continue
575+
}
576+
major, _ := strconv.Atoi(m[1])
577+
minor, _ := strconv.Atoi(m[2])
578+
l := line{major, minor}
579+
if prev, ok := frozen[l]; !ok || when.Before(prev) {
580+
frozen[l] = when
581+
}
582+
}
583+
return frozen, nil
584+
}
585+
496586
// targetsAt reports the current and previous release lines as of when, which is
497587
// what the `kind/backport` and `kind/backport-previous` labels meant at that
498588
// moment.
589+
//
590+
// The lines that exist at that point are ranked by version, not by when they
591+
// opened, matching the numeric descending sort backport.yaml applies to its
592+
// branch list. The two orders normally coincide, and stop coinciding as soon
593+
// as a freeze overlaps the previous line's stabilisation: cut vX.(Y+1).0-rc.1
594+
// while vX.Y.0 is still unpublished and the newer line opens first in time
595+
// while still being the newer line. Ranking by version is also what keeps
596+
// release-1.10 above release-1.9.
499597
func targetsAt(opened []lineOpen, when time.Time) (current, previous *line) {
500598
var live []line
501599
for _, o := range opened {
502600
if !o.when.After(when) {
503601
live = append(live, o.line)
504602
}
505603
}
604+
sort.Slice(live, func(i, j int) bool { return live[j].less(live[i]) })
506605
if n := len(live); n > 0 {
507-
current = &live[n-1]
606+
current = &live[0]
508607
if n > 1 {
509-
previous = &live[n-2]
608+
previous = &live[1]
510609
}
511610
}
512611
return current, previous

0 commit comments

Comments
 (0)