Skip to content

Commit 5a53e8a

Browse files
luisleo526claude
andcommitted
ci: teach main's GKE admission rules the arm leg of the PR workflow, as two exact variants
The PR workflow's admit job runs main's admission rules on the pull request's own gke-pr.yml before any privileged leg runs. A PR that adds the arm64 leg (a build-arm job, an arm_relevant admit output, and matching legs and result checks) is refused by those rules, and the base checker's ci_docs_only.py does not publish arm_relevant, so the new result check would also fail with an unanswered classification. This change is the main-side half of that PR and does not touch gke-pr.yml: - ci_docs_only.py publishes arm_relevant (true for sources, build inputs and test scripts and for any path it cannot classify; false for established docs-only and .github-only changes), with its tests. - ci_preflight.py admits exactly two shapes of gke-pr.yml. The shape that has no build-arm job is checked by the unchanged rules. The shape that defines build-arm is checked by the full new rule set: the job inventory, the arm_relevant output, the pinned arm64 label, the path policy, the exact setup and Debug steps, and the complete legs and result gate bodies. The two sets are selected together by the job definition and never mixed, so a hybrid, a second arm job, an extra job in either shape, another label, or a container, services, credentials or timeout on the arm job match neither shape and are refused. In the arm shape, continue-on-error anywhere in the arm job and env, shell or working-directory on any arm step are refused too. - test_ci_preflight.py runs the real rules against main's current workflow and the same workflow with the arm leg applied, and asserts the exact findings of each refusal control. - docs/ci.md documents the classifier and both admission variants without changing the file's line count. Its rewritten sentences are named here, as the documentation check for unnamed sentence deletions (introduced by f85ce18) requires: "First merge the checker or allow-table change while the existing workflows pass." and "Then merge the workflow change that uses the newly admitted rule or label." and "Rule and table changes land in two steps." and "This order prevents one pull request from changing both sides of admission." are now one sentence (rule and table changes land first while existing workflows pass, workflow changes follow, so one PR cannot change both sides of admission); "The classifier uses exact `.github/` and `docs/` prefixes, so lookalike directories and the classifier itself cannot create a skip." and "Renames contribute both names; empty, missing, malformed, truncated or unreadable lists are neither class." are folded into the shorter paragraph that describes the path file and the exact prefixes, with the new arm_relevant output described beside it. Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
1 parent 2cbf75b commit 5a53e8a

5 files changed

Lines changed: 725 additions & 56 deletions

File tree

‎docs/ci.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,15 @@ every profile. `ci.yml` retains authorization and draft event handling;
2727
and GitHub-only changes still run preflight, while only the proof legs skip.
2828
Failed, cancelled or unclassified work is red in the hosted result.
2929

30-
A GitHub-only PR changes at least one path, with every changed path under
31-
`.github/`, including both sides of a rename. `scripts/ci_*.py` changes,
32-
alone or mixed with `.github/`, follow the ordinary proof plan. `gke-pr`
33-
reads the SHA-bound three-dot compare API twice, writes names to a
34-
NUL-separated file and gives that file to the base tree's
35-
`scripts/ci_docs_only.py --paths` classifier. Renames contribute both names;
36-
empty, missing, malformed, truncated or unreadable lists are neither class.
37-
The classifier uses exact `.github/` and `docs/` prefixes, so lookalike
38-
directories and the classifier itself cannot create a skip.
30+
A GitHub-only PR changes at least one path, all under `.github/`, including both sides of a rename.
31+
`scripts/ci_*.py` changes, alone or mixed with `.github/`, follow the ordinary proof plan.
32+
`gke-pr` reads the SHA-bound three-dot compare API twice, writes a NUL-separated path file and gives it to the base tree's `scripts/ci_docs_only.py --paths`.
33+
Empty, missing, malformed, truncated or unreadable lists are neither class; exact `.github/` and `docs/` prefixes prevent lookalikes or the classifier itself from creating a skip.
34+
35+
The classifier also emits `arm_relevant`: source/build inputs under `tests/`, `runner/`, `include/`, `src/` or `docker/` set it true,
36+
as do C/C++ and CMake sources (including third-party sources), `CMakeLists.txt` and `scripts/test_*`.
37+
Unknown paths and empty, unreadable or malformed lists set it true; established docs-only or `.github/`-only PRs and mixed docs/GitHub paths alone set it false.
38+
Both compare reads use the base classifier; the unchanged main workflow does not publish this output or schedule a PR arm leg.
3939

4040
`--tier github-only` runs `shellcheck-version`, `actionlint-runner-labels`,
4141
`runner-allowlist`, `workflow-lint`, `ci-workflow-contract`, `docs-workflow-contract` and
@@ -1989,10 +1989,10 @@ The scanner runs actionlint before its structural text rules.
19891989
The main branch rule table and parser grammar judge the fetched head workflows.
19901990
A workflow change that needs a loosened rule must therefore use two changes.
19911991

1992-
Rule and table changes land in two steps.
1993-
First merge the checker or allow-table change while the existing workflows pass.
1994-
Then merge the workflow change that uses the newly admitted rule or label.
1995-
This order prevents one pull request from changing both sides of admission.
1992+
Rule and table changes land first while existing workflows pass; workflow changes follow, so one PR cannot change both sides of admission.
1993+
`gke-pr.yml` admits exactly two variants: OLD keeps the current jobs, outputs and gate bodies; defining the `build-arm` job selects all NEW checks together.
1994+
NEW requires the exact arm classifier output, fixed Debug job on bare `gke-16cpu-32gb-arm64`, arm-aware `legs` needs/check and independent `result` check.
1995+
Hybrids and extra jobs, outputs, needs or arm steps are refused; OLD retains its original exact rules and templates while the workflow change waits for a separate PR.
19961996
The github-only class still runs the full workflow policy preflight.
19971997
The proof legs are the only jobs skipped for the two documentation classes.
19981998
The hosted result requires admission and preflight success in every class.

‎scripts/ci_docs_only.py‎

Lines changed: 34 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,15 @@
4444
4545
reads GITHUB_EVENT_NAME, and PR_HEAD_SHA (pull request) or PUSH_BEFORE and
4646
PUSH_FORCED (push), from the environment. It prints its reasons, appends
47-
``docs_only=true|false`` and ``github_only=true|false`` to FILE, and exits 0
47+
``docs_only=true|false``, ``github_only=true|false`` and
48+
``arm_relevant=true|false`` to FILE, and exits 0
4849
whatever it decides. ``--paths`` reads a complete NUL-separated list as data;
4950
an unreadable or unterminated list is neither class. The classifier is held by
5051
scripts/test_ci_docs_only.py (a ci_preflight stage).
52+
53+
Arm proof is required for source/build inputs and test scripts, and for any
54+
path the rule cannot classify. Missing or empty change data also requires it.
55+
An established docs-only or GitHub-only PR never requires arm proof.
5156
"""
5257
from __future__ import annotations
5358

@@ -61,6 +66,8 @@
6166
ROOT = Path(__file__).resolve().parent.parent
6267
# CI itself, and Markdown the proof jobs' own rows read: never documentation.
6368
NOT_DOCUMENTATION_DIRS = ('.github/', 'benchmarks/', 'scripts/', 'tests/')
69+
ARM_SOURCE_DIRS = ('tests/', 'runner/', 'include/', 'src/', 'docker/')
70+
ARM_SOURCE_EXTENSIONS = ('.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.cmake')
6471
# Documentation inputs whose checks run outside preflight, in a proof job's
6572
# CTest row or the docs workflow, with each input's check home. These inputs
6673
# remain excluded from docs-only skips.
@@ -96,18 +103,28 @@ def is_documentation(path: str) -> bool:
96103
return path.startswith('docs/') or name.endswith('.md')
97104

98105

99-
def classify_paths(paths: list[str], *, pull_request: bool = True) -> tuple[bool, bool]:
100-
"""Return ``(docs_only, github_only)`` for already collected path data.
106+
def is_arm_relevant(path: str) -> bool:
107+
"""Recognize source/test inputs; unknown paths require arm proof too."""
108+
name = path.rsplit('/', 1)[-1]
109+
if (path.startswith(ARM_SOURCE_DIRS) or path.startswith('scripts/test_')
110+
or name == 'CMakeLists.txt' or name.endswith(ARM_SOURCE_EXTENSIONS)):
111+
return True
112+
return not (is_documentation(path) or path.startswith('.github/'))
113+
114+
115+
def classify_paths(paths: list[str], *, pull_request: bool = True) -> tuple[bool, bool, bool]:
116+
"""Return ``(docs_only, github_only, arm_relevant)`` for collected paths.
101117
102118
The caller supplies both sides of a rename. No path is normalized: names
103119
containing newlines, quotes or ``..`` are still names, and only the exact
104120
directory prefixes below classify them.
105121
"""
106122
if not paths:
107-
return False, False
123+
return False, False, True
108124
docs_only = all(is_documentation(path) for path in paths)
109125
github_only = pull_request and all(path.startswith('.github/') for path in paths)
110-
return docs_only, github_only
126+
arm_relevant = not (docs_only or github_only) and any(is_arm_relevant(path) for path in paths)
127+
return docs_only, github_only, arm_relevant
111128

112129

113130
def read_paths_file(path: Path) -> tuple[list[str] | None, str]:
@@ -172,18 +189,18 @@ def changed_paths(root: Path, base: str, head: str) -> list[str]:
172189
return [path for path in listed.split('\0') if path]
173190

174191

175-
def classify(env: dict[str, str], root: Path = ROOT) -> tuple[bool, bool, list[str]]:
176-
"""(docs_only, github_only, reasons printed for them)."""
192+
def classify(env: dict[str, str], root: Path = ROOT) -> tuple[bool, bool, bool, list[str]]:
193+
"""(docs_only, github_only, arm_relevant, reasons printed for them)."""
177194
try:
178195
base, head, what = compared(env, root)
179196
paths = changed_paths(root, base, head)
180197
except Doubt as doubt:
181-
return False, False, [f'not docs-only: {doubt}']
198+
return False, False, True, [f'not docs-only: {doubt}']
182199
lines = [f'{what}: {base}..{head}, {len(paths)} changed path(s)']
183-
docs_only, github_only = classify_paths(
200+
docs_only, github_only, arm_relevant = classify_paths(
184201
paths, pull_request=env.get('GITHUB_EVENT_NAME') == 'pull_request')
185202
if not paths:
186-
return False, False, lines + ['not docs-only: the change is empty']
203+
return False, False, True, lines + ['not docs-only: the change is empty']
187204
other = [path for path in paths if not is_documentation(path)]
188205
if other:
189206
lines.append(f'not docs-only: {len(other)} changed path(s) are not documentation')
@@ -197,12 +214,12 @@ def classify(env: dict[str, str], root: Path = ROOT) -> tuple[bool, bool, list[s
197214
if len(paths) > SHOWN else [])
198215
if github_only:
199216
lines.append('github-only: every changed path is under .github/')
200-
return docs_only, github_only, lines
217+
return docs_only, github_only, arm_relevant, lines
201218

202219

203220
def decide(env: dict[str, str], root: Path = ROOT) -> tuple[bool, list[str]]:
204221
"""(docs_only, the reasons printed for it), preserving the old API."""
205-
docs_only, _, lines = classify(env, root)
222+
docs_only, _, _, lines = classify(env, root)
206223
return docs_only, lines
207224

208225

@@ -214,28 +231,29 @@ def main(argv: list[str] | None = None) -> int:
214231
parser.add_argument('--paths', type=Path,
215232
help='read a complete NUL-separated compare-file list')
216233
parser.add_argument('--github-output', type=Path,
217-
help='append docs_only=true|false and github_only=true|false to this file')
234+
help='append docs_only, github_only and arm_relevant flags to this file')
218235
args = parser.parse_args(argv)
219236
if args.paths is not None:
220237
paths, reason = read_paths_file(args.paths)
221238
if paths is None:
222-
docs_only, github_only = False, False
239+
docs_only, github_only, arm_relevant = False, False, True
223240
lines = [f'not docs-only/github-only: {reason}']
224241
else:
225-
docs_only, github_only = classify_paths(paths)
242+
docs_only, github_only, arm_relevant = classify_paths(paths)
226243
lines = [reason]
227244
lines.append('docs-only: every changed path is documentation'
228245
if docs_only else 'not docs-only: a changed path is not documentation')
229246
lines.append('github-only: every changed path is under .github/'
230247
if github_only else 'not github-only: a changed path is outside .github/')
231248
else:
232-
docs_only, github_only, lines = classify(dict(os.environ), args.root)
249+
docs_only, github_only, arm_relevant, lines = classify(dict(os.environ), args.root)
233250
for line in lines:
234251
print(line)
235252
if args.github_output is not None:
236253
with args.github_output.open('a', encoding='utf-8') as output:
237254
output.write(f'docs_only={"true" if docs_only else "false"}\n')
238255
output.write(f'github_only={"true" if github_only else "false"}\n')
256+
output.write(f'arm_relevant={"true" if arm_relevant else "false"}\n')
239257
return 0
240258

241259

0 commit comments

Comments
 (0)