docs(contributing): state the bar — documentation standard, gates, tests-first - #299
Merged
Conversation
…sts-first The repo's signature is documentation that argues, and nobody will guess that standard (#282). CONTRIBUTING.md now teaches it from a worked example quoted out of guards.py — pinned by tests/test_contributing.py so the quote cannot drift from the source — beside the dev setup and gates, the tests-first expectation, Conventional Commits, and three-tier scope guidance. Governance and licence sections from Phase 6 kept intact.
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
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.
Closes #282
The repository's documentation standard is its signature and its single biggest barrier to
contribution — nobody will guess it. An unstated bar filters for clairvoyance: PRs arrive at
ordinary quality, get heavy review, and the contributor quietly leaves.
What CONTRIBUTING.md now states
_open_exposure_by_assetdocstring in
keel/execution/guards.pyis quoted in full, then dissected on the threeproperties that make it acceptable — it says why, it names what was measured, and it
says what it would take to change the decision.
uv sync --all-extras --dev,uv run ruff check,uv run mypy,uv run pytest -q— pasteable, because a gate nobody can paste is a gatenobody runs.
assertion, not an import error — carried in the PR.
keel-broker-apisurface) / out of scope (rulings as defaults, "make the bot profitable",weakening fails-closed paths).
why.
Tests (
tests/test_contributing.py, red first): gates stated verbatim; the workedexample present in CONTRIBUTING.md and still existing in guards.py (drift-proof, via
wrap/blockquote-normalized matching); the three properties named; tests-first + evidence;
commit convention; scope tiers.
Gates:
pytest2788 passed / 1 skipped,ruff checkclean,mypyclean.