docs: publish this project's exit-code contract, and flag the family collision - #34
Merged
Conversation
…collision
These four sibling projects each call their exit codes a public contract -- CI
gates and onboarding scripts branch on them -- and none documented the full set
in one place. Stage C of the plan says to *flag* the cross-project collision
rather than fix it by extracting a shared library, because that would couple
four independent release cycles and one of these projects deliberately ships
with no dependencies at all.
docs/exit-codes.md now states this project's own codes, and
test_exit_codes_documented.py fails if the document and the code disagree in
either direction. A documented contract that is wrong is worse than an
undocumented one, because wrappers get written from the document.
Verifying the collision rather than repeating the plan's description of it
changed two things about that description.
The plan said "only 0 agrees". Right in substance: 0 means success in all four,
though devrepro-doctor names it READY rather than OK.
It also said devrepro-doctor is "the inverse of AVL/LAHB on 2/3/4". It is not
an inversion. api-verity-lab has usage=2 and internal=4; devrepro-doctor has
usage=4 and internal=3. The meanings rotate rather than swap, and calling it an
inverse would have put a wrong statement into a document about correctness.
The genuinely dangerous collision is code 1:
api-verity-lab 1 = findings detected (a gate should fail)
devrepro-doctor 1 = READY_WITH_WARNINGS (a gate should pass)
tooltrace-bench 1 = error
local-ai-hardware-bench 1 = validation error
A wrapper that treats any non-zero status as failure blocks on a DevRepro run
that reported the machine as usable. The second is code 2: an operator mistake
in two of them, and devrepro-doctor's most important verdict -- the machine
cannot build this project -- in the third.
Verified: ruff, ruff format, mypy, full suite green, every link in the new
document resolves.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
…nk inside the site Two mistakes of mine, both of which only showed up on Linux CI. The test opened `docs/exit-codes.md`. This repository's file is `docs/EXIT-CODES.md` -- the name mkdocs.yml has always referenced. Windows resolves those to the same file, so the test passed locally and failed across the entire Python matrix in CI. The path now matches what git tracks. The same case-insensitivity meant my generator's write to `docs/exit-codes.md` landed on the existing `EXIT-CODES.md` rather than creating a second file, which is the only reason this is a naming fix rather than a duplicate document. The docs build then failed separately: `mkdocs build --strict` rejects a relative link that leaves the documentation tree, and I had linked `../devrepro/core/exit_codes.py`. My earlier check confirmed every link resolved on the filesystem, which was true and beside the point -- mkdocs asks a different question. An absolute GitHub URL satisfies both renderers. Also corrects requirements-docs.txt, whose comment claimed the pin was "below 9.7" for licensing reasons and that "9.6.x remains ISC". Three things wrong with that: the pin had already been moved to >=9.7.7 by the Dependabot bump in number 17, crossing the very boundary the comment declared; mkdocs-material is MIT at 9.5, 9.6, 9.7.0 and 9.7.7 by PyPI's own classifiers; and there is no ISC line. The pin is fine on reproducibility grounds and now says so. The lesson worth keeping is that an automated bump walked straight through a stated constraint, because the constraint lived in a comment nothing enforced.
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
1 participant
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.
These four sibling projects each call their exit codes a public contract — CI gates and onboarding scripts branch on them — and none documented the full set in one place.
Stage C of the plan says to flag the cross-project collision rather than fix it by extracting a shared library. A shared library would couple four independent release cycles, and one of these projects deliberately ships with no dependencies at all.
docs/exit-codes.mdnow states this project's own codes, andtest_exit_codes_documented.pyfails if the document and the code disagree in either direction. A documented contract that is wrong is worse than an undocumented one, because wrappers get written from the document.Verifying the collision changed two things about the plan's description
The plan said "only 0 agrees". Right in substance — 0 means success in all four, though
devrepro-doctornames itREADYrather thanOK.It also said
devrepro-doctoris "the inverse of AVL/LAHB on 2/3/4". It is not an inversion.api-verity-labhas usage=2, internal=4;devrepro-doctorhas usage=4, internal=3. The meanings rotate rather than swap — and calling it an inverse would have put a wrong statement into a document about correctness.The genuinely dangerous collision is code 1
api-verity-labdevrepro-doctorREADY_WITH_WARNINGStooltrace-benchlocal-ai-hardware-benchA wrapper that treats any non-zero status as failure blocks on a DevRepro run that reported the machine as usable.
The second is code
2: an operator mistake in two of them, anddevrepro-doctor's most important verdict — the machine cannot build this project — in the third.Verification
ruff·ruff format --check·mypy· full suite green · every link in the new document resolves · drift test verified by renaming a documented code and watching it fail.