diff --git a/docs/caller-workflow.yml b/docs/caller-workflow.yml index 178db6a..21fed07 100644 --- a/docs/caller-workflow.yml +++ b/docs/caller-workflow.yml @@ -1,8 +1,13 @@ # Copy this to .github/workflows/code-review.yml in the target repository. -# Change the two things marked CHANGE ME and nothing else. +# For an SDK repository, change nothing. For anything else, read the two +# CHANGE ME notes. # # This is the shape that works. It is not the obvious shape, and the comments # say why, because every deviation below was paid for once already. +# +# It should need NO edit at all for an SDK repository: every one of them names +# its pull-request CI `Tests`, and every one of them is public and on the +# MarketDataApp account, so `runs-on` is already right. name: Code review @@ -17,11 +22,19 @@ name: Code review # notice. Do not add it back without reading `require_ci_green` first. on: workflow_run: - # CHANGE ME: the `name:` of every CI workflow whose result the review should - # wait for -- not the filename. Name them ALL: the gate looks at every check - # on the commit, so whichever finishes last is the one whose review actually - # proceeds. The earlier triggers skip cheaply, and a repeat on the same head - # skips too, so extra triggers are self-deduplicating rather than wasteful. + # LEAVE THIS ALONE. Every SDK repository names its pull-request CI `Tests`, + # which is what makes this file identical everywhere -- see + # docs/setup.md section 4a. It is the workflow's `name:`, never its filename. + # + # Both are named because the gate looks at EVERY check on the commit, so + # whichever finishes last is the one whose review actually proceeds; the + # earlier trigger skips cheaply, and a repeat on the same head skips too, so + # extra triggers are self-deduplicating rather than wasteful. + # + # Naming a workflow this repository does not have is harmless -- only sdk-py + # has a separate `Lint`; the others lint inside `Tests` -- because a name + # that never occurs never matches. If you add a CI workflow whose result + # should gate a review, add its name here. workflows: ["Tests", "Lint"] types: [completed] issue_comment: diff --git a/docs/setup.md b/docs/setup.md index a03b225..b3657f5 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -170,6 +170,33 @@ If you pin `uses:` to a branch or tag, pin `bot-ref` to the **same** ref. default is `main`. A mismatch fails with `invalid choice` on whichever command the older side lacks. +### 3a. The CI workflow must be named `Tests` + +The trigger matches a workflow by its `name:`, so the name is an interface. All +five SDK repositories now use `Tests`, which is what lets one caller file be +copied without edits. + +They did not start that way — `Tests` in sdk-go, sdk-php and sdk-py, `CI` in +sdk-js, `Pull Request` in sdk-java — and naming the wrong one **fails silently**: +no review ever runs and nothing says why. sdk-java is the trap, because its +`Main` workflow looks like the obvious candidate and only runs on pushes to the +default branch. + +**Find the right workflow empirically, not from filenames.** Look at which +checks actually appear on an open pull request: + +```bash +sha=$(gh api repos///pulls/ --jq .head.sha) +gh api "repos///commits/$sha/check-runs" --jq '.check_runs[].name' +``` + +then find which workflow produces them. Rename that workflow to `Tests`. + +**Renaming is safe.** Every required status check in these repositories is a +**job** name, not a workflow name — `test (3.10)`, `Verify (JDK 17)`, +`check (20.x)` — so branch protection is untouched. The only thing that moves is +the label in the Actions list. + ### 4. Add a policy, if the defaults are not what you want `.github/code-review/policy.yml` on the **base** branch. Absent keys keep the diff --git a/tests/test_workflow.py b/tests/test_workflow.py index 2c2874d..0526dec 100644 --- a/tests/test_workflow.py +++ b/tests/test_workflow.py @@ -534,3 +534,22 @@ def test_the_caller_template_still_names_its_secrets(): "CODE_REVIEW_APP_PRIVATE_KEY", "CLAUDE_CODE_OAUTH_TOKEN", } + + +def test_the_caller_template_needs_no_edit_for_an_sdk_repository(): + """The workflow name is an interface, so it is standardised, not per-repo. + + They diverged -- Tests in sdk-go/sdk-php/sdk-py, CI in sdk-js, Pull Request + in sdk-java -- and naming the wrong one fails SILENTLY: no review runs and + nothing says why. All five now use `Tests`, which is what lets this file be + copied without edits. + """ + assert CALLER[ON]["workflow_run"]["workflows"] == ["Tests", "Lint"] + text = (ROOT / "docs/caller-workflow.yml").read_text() + assert "LEAVE THIS ALONE" in text + # The TRIGGER block specifically: `runs-on` still carries a CHANGE ME, for a + # repository that is private or outside the organisation, and that is right. + triggers = text[text.index("\non:"):text.index("\njobs:")] + assert "CHANGE ME" not in triggers, ( + "the trigger block must need no edit for an SDK repository" + )