The docs job checks out the ctrlrun-docs branch of the same name, or main - #180
Merged
Merged
Conversation
…main Every run of `ci.yml` since PR #174 merged has been red, and every one at the same step: `render_api.py --check`, eleven and then fifteen pages under docs/reference/api differing from the docstrings. The pages were regenerated in CTRLRun/ctrlrun-docs on the day, against the whole v0.10 stack, and that branch could not merge either: its own CI checks pages against this repository's `main`, which had two of the five items. Each side was waiting for the other, by construction, for the length of the release cycle. The cause is one line: the `docs` job checked out ctrlrun-docs at `main`, whatever it was checking. A page describes a commit, and the page for a commit that has not merged cannot be on `main` yet, so every pull request that touched a docstring or a `--help` was red until it merged, and a check that is always red is a check nobody reads. The ruleset does not require `docs`, so nothing was blocked; `badge` and `notify-docs` need it, so the test-count badge stopped moving at item 1 and ctrlrun-docs received no dispatch. Now the job asks ctrlrun-docs for a branch named after the one under test (`github.head_ref` on a pull request, `github.ref_name` on a push) and checks out that one when it exists, `main` otherwise. A branch here that changes a signature is accompanied by a branch there of the same name, regenerated against it, and each is checked against the other; ctrlrun-docs' CI gains the mirror image in the same-named branch there. `main` is checked against `main`, so the pages on `main` are expected to match this repository's `main` at all times: the docs branch merges when the kernel branch does, the code first. The fallback is `main` and not a skip, for the reason the `continue-on-error` flags left this job: a branch that forgot its pages is a red job, not a green one that verified nothing. The branch name reaches the shell through `env:` and never inline in the script, so a branch called `$(...)` is a string and not a command, which is also what Scorecard's Dangerous-Workflow check reads for. The match is exact and fixed-string, because `ls-remote` matches a pattern against the tail of a ref and `.` in a version is a regex wildcard. CONTRIBUTING.md says where the pages for a change go, in the section that already said the checks read both trees. No test changes: `test_the_badge_job_publishes_the_badge_the_verify_job_produced` and ctrlrun-docs' `test_ci_publishes_the_test_count_badge_after_the_suite_has_passed` read the job's `needs:`, its `if:` and its write step, none of which moved. Signed-off-by: arpan <contact@arpanghoshal.com>
|
Warning Review limit reachedNext included review available in 49 minutes. View limit detailsLimit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Review configuration: ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (2)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why every run since #174 has been red
Every
ci.ymlrun since PR #174 merged failed at the same step:render_api.py --check, eleven and then fifteen pages underdocs/reference/apidiffering from the docstrings. Thedocsjob checked outCTRLRun/ctrlrun-docsatmain, whatever commit it was checking, and the page for a commit that has not merged cannot be onmainyet. So every pull request that touched a docstring or a--helpwas red until it merged, and ctrlrun-docs PR #14, regenerated against the whole v0.10 stack, was red the other way round because that repository's CI checks pages against this one'smain. Each side waited for the other, by construction.The ruleset does not require
docs, so nothing was blocked.badgeandnotify-docsneed it, so the test-count badge stopped moving at item 1 and ctrlrun-docs received no dispatch.What changes
The
docsjob asks ctrlrun-docs for a branch named after the one under test (github.head_refon a pull request,github.ref_nameon a push) and checks out that one when it exists,mainotherwise. A branch here that changes a signature is accompanied by a branch there of the same name, regenerated against it, and each is checked against the other.mainis checked againstmain, so the pages onmainare expected to match this repository'smainat all times: the docs branch merges when the kernel branch does, the code first. CONTRIBUTING.md says so in the section that already said the checks read both trees.The fallback is
mainand not a skip: a branch that forgot its pages is a red job, not a green one that verified nothing. The branch name reaches the shell throughenv:, never inline in the script (Scorecard's Dangerous-Workflow check reads for that), and the match is exact and fixed-string becausels-remotematches a pattern against the tail of a ref.The pair
CTRLRun/ctrlrun-docs#15 is the same-named branch: the mirror-image CI change there, plus the pages regenerated against this repository's
mainas it stands (v0.10 items 1 to 5), which is what makes this PR'sdocsjob green and will makemain's green once both merge. Merge order: this PR, then that one.Checks
test_repository_signals.py,test_verify_action.pyandtest_packaging.pypass locally excepttest_T118, which reads the installed package and fails identically onmainin this environment (the venv's editable install points at an older checkout). No test asserts on the step that was added; the ones that read thedocsjob assertneeds:,if:and the write step, none of which moved.🤖 Generated with Claude Code