Skip to content

Commit aea61f7

Browse files
docs(release): say which CRD and API changes rule 4 lets through
The policy page told contributors that a new optional field reaches patch releases. It does not, and the tool now holds one back, while a change that only rewrites description text in a CRD's schema now goes through. Readers decide whether to split a fix out of a larger pull request by this sentence, so it has to match what the batch does. Assisted-By: LLM Signed-off-by: Myasnikov Daniil <[email protected]>
1 parent 81c7108 commit aea61f7

3 files changed

Lines changed: 4 additions & 4 deletions

File tree

‎cmd/backport-batch/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,9 +66,9 @@ Prints the release lines the batch runs for, newest first: of the `release-X.Y`
6666

6767
## Rule 4 and the API review gate
6868

69-
A change to the API is held back only when the [API review gate](../../.github/workflows/api-review-gate.yaml) would call it sizeable. The gate is asked whenever an original changes something it parses: `pkg/apiserver/apiserver.go`, an ApplicationDefinition under `packages/system/*-rd/cozyrds/`, or a `.yaml` or `.yml` file under `packages/` or `internal/` that holds `CustomResourceDefinition` or `APIService` before or after the merge. An edit to the Go types under `api/` alone reaches none of them, so the gate would see no change. The batch calls the gate's own code, `apigate.LoadSnapshot` and `apigate.Classify` from `internal/apigate`, on the trees of the original's first parent and of its merge commit. It reads only what the gate reads, from `git ls-tree` and `git cat-file` into a temporary directory, so no attribute or export rule changes what the gate sees. A reworded description or a new optional field passes; a new or removed group or resource, or a schema change that can reject what the old schema accepted, does not. Migrations, `targetVersion` and CRDs keep their own checks: the gate sees only first-party `cozystack.io` CRDs, and only their sizeable changes, while a vendored operator's CRD is just as unsafe in a patch.
69+
A change to the API is held back when the [API review gate](../../.github/workflows/api-review-gate.yaml) would call it sizeable, and when it adds a field to a schema the gate reads, a CRD's or an ApplicationDefinition's. The gate is asked whenever an original changes something it parses: `pkg/apiserver/apiserver.go`, an ApplicationDefinition under `packages/system/*-rd/cozyrds/`, or a `.yaml` or `.yml` file under `packages/` or `internal/` that holds `CustomResourceDefinition` or `APIService` before or after the merge. An edit to the Go types under `api/` alone reaches none of them, so the gate would see no change. The batch calls the gate's own code, `apigate.LoadSnapshot` and `apigate.Classify` from `internal/apigate`, on the trees of the original's first parent and of its merge commit. It reads only what the gate reads, from `git ls-tree` and `git cat-file` into a temporary directory, so no attribute or export rule changes what the gate sees. A reworded description passes; a new or removed group or resource, or a schema change that can reject what the old schema accepted, does not. Nor does a new field, optional or not, which the gate passes as additive: on the same snapshots the batch lists the fields each schema declares, at every depth the gate's own diff walks, the properties of an object, the items of an array and the values of a map, and holds back a merge whose schemas declare one the parent's did not. A version new to a resource counts every field it declares. A field declared only under `allOf`, `anyOf` or `oneOf` is not listed, since the gate's diff does not walk those either. The resources `pkg/apiserver/apiserver.go` registers, whose schema lives only in the Go types under `pkg/apis`, carry no schema the gate reads, so a field added to one of them is not seen at all. Migrations, `targetVersion` and CRDs keep their own checks: the gate sees only first-party `cozystack.io` CRDs, and only their sizeable changes, while a vendored operator's CRD is just as unsafe in a patch.
7070

71-
The CRD check works document by document. In every changed manifest, a YAML, JSON or `.tpl` file or anything under `templates/` or `crds/`, outside `tests/` and `testdata/`, every document that names `CustomResourceDefinition` is read as YAML, which takes JSON too, and the CRDs among them are compared between the parent and the merge by `metadata.name`, compact JSON and quoted keys included. The change counts only when one was added, removed or edited, so an edit to the DaemonSet beside a CRD in one manifest does not, and neither does a sentence or a `lookup` call that merely names the kind. A document that declares `kind: CustomResourceDefinition` on a line of its own but cannot be read as an object, a CRD behind a Helm template guard for one, is compared by its text, so the check fails closed on it, and so does a `List` that holds a CRD.
71+
The CRD check works document by document. In every changed manifest, a YAML, JSON or `.tpl` file or anything under `templates/` or `crds/`, outside `tests/` and `testdata/`, every document that names `CustomResourceDefinition` is read as YAML, which takes JSON too, and the CRDs among them are compared between the parent and the merge by `metadata.name`, compact JSON and quoted keys included. The change counts only when one was added, removed or edited, so an edit to the DaemonSet beside a CRD in one manifest does not, and neither does a sentence or a `lookup` call that merely names the kind. Nor does rewording the `description` text of a CRD's schema, at any depth: each named CRD is compared as an object with the `description` of every schema under `spec.versions[].schema.openAPIV3Schema` dropped, which tells that keyword from a field called `description`, a printer column's description or one inside a `default`, and as its text without the `description` entries, each the key's line and every line indented under it, so a comment or any other line outside such an entry still counts. A field added to the schema counts, optional or not, and so does every change other than to description text. In a file Helm renders as a template, anything under `templates/` or a `.tpl`, a CRD that holds a template action, `{{`, is compared by its whole text, since what the action renders is not known. Any other file, one a chart inserts with `.Files.Get` or keeps under `crds/` included, is compared as plain text, so braces in a description that quotes a Go template are text. A chart that passes such a file through `tpl`, as the vertical-pod-autoscaler chart does with its `files/crds/`, renders it all the same, and the check does not detect that; no file in the tree today holds a CRD that both parses and carries an action on a description line that way, and the vertical-pod-autoscaler files do not parse, so they are compared whole. A description the text comparison does not find, in a CRD written as JSON, under a quoted key or in flow style, counts as an edit when it changes. A document that declares `kind: CustomResourceDefinition` on a line of its own but cannot be read as an object, a CRD behind a Helm template guard for one, is compared by its text, so the check fails closed on it, and so does a `List` that holds a CRD.
7272

7373
## Maintainer overrides
7474

‎docs/release/backport-mechanics.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ go build ./cmd/backport-batch
1818

1919
### Backporting code that touches monotonic counters
2020

21-
The batch never takes a change like this: rule 4 in [Backports](./backports.md) holds migrations, `targetVersion`, sizeable API changes and CRDs for the next minor. What follows is why, and what a maintainer has to do when a migration must reach a release line anyway.
21+
The batch never takes a change like this: rule 4 in [Backports](./backports.md) holds migrations, `targetVersion`, sizeable API changes, added fields and CRD edits other than reworded descriptions for the next minor. What follows is why, and what a maintainer has to do when a migration must reach a release line anyway.
2222

2323
Migrations are the canonical case. `packages/core/platform/images/migrations/run-migrations.sh` is a linear counter — it runs `seq $CURRENT_VERSION $((TARGET_VERSION - 1))` and stops if `CURRENT >= TARGET`. This creates a forward-upgrade trap. Walking through it with `release-1.2` as the maintenance branch:
2424

‎docs/release/backports.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ The batch takes a pull request from `main` into release line X.Y when all of the
1515
1. It merged into `main` after `release-X.Y` branched, or after the line started under this policy if that is later (see [Where each line starts](#where-each-line-starts)), and the line does not carry it yet.
1616
2. Its title type is `fix` or `security`, the type of a fix that comes through a security advisory. CI and e2e fixes count, because they keep the line's own CI working. The title is read once any leading `[Backport …]` prefixes are dropped, and a title that does not read as a Conventional Commits title is kept out.
1717
3. It is not breaking: no `!` after the type or scope, and no `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer at the start of any line of the description its merge into `main` recorded. A footer inside an HTML comment, where the pull request template quotes it, does not count.
18-
4. It touches no platform migrations, anything under `packages/core/platform/images/migrations/migrations/`, and no `targetVersion` line of `packages/core/platform/values.yaml`, adds, removes or edits no CustomResourceDefinition document (a CRD in a test fixture under `tests/` or `testdata/` does not count, and neither does an edit to another document in the same file), and makes no change to the API that the [API review gate](../../.github/workflows/api-review-gate.yaml) calls sizeable: a new or removed API group or resource, or a schema change that can reject what the old schema accepted. Those wait for the next minor; a reworded description or a new optional field under `api/` does not. [Backporting code that touches monotonic counters](./backport-mechanics.md#backporting-code-that-touches-monotonic-counters) shows what a migration on a release line breaks.
18+
4. It touches no platform migrations, anything under `packages/core/platform/images/migrations/migrations/`, and no `targetVersion` line of `packages/core/platform/values.yaml`, adds, removes or edits no CustomResourceDefinition document (a CRD in a test fixture under `tests/` or `testdata/` does not count, and neither does an edit to another document in the same file), and makes no change to the API that the [API review gate](../../.github/workflows/api-review-gate.yaml) calls sizeable: a new or removed API group or resource, or a schema change that can reject what the old schema accepted. Nor does it add a field to a CRD's or an ApplicationDefinition's schema, whether the field is optional or not. Those wait for the next minor. A change that only rewrites `description` text in a CRD's or an ApplicationDefinition's schema does not, unless the CRD writes that description other than as a plain `description:` key in block YAML (in JSON, under a quoted key or in flow style), or sits in a Helm template that holds a template action: then the rewording counts as an edit. [Backporting code that touches monotonic counters](./backport-mechanics.md#backporting-code-that-touches-monotonic-counters) shows what a migration on a release line breaks.
1919
5. Each of its commits picks cleanly with `git cherry-pick -x`, or its conflict is resolved during the batch, and the batch's build and tests pass. A pick that fails moves to the next batch, and the batch pull request lists it with the files that conflicted.
2020
6. On an older line, it is already on the next newer line the batch runs for. Lines are processed newest first, so an older line takes only what the newer one already carries.
2121

0 commit comments

Comments
 (0)