Skip to content

docs(contributing): state the bar — documentation standard, gates, tests-first - #299

Merged
eaitbrahim merged 1 commit into
mainfrom
docs/contributing-standard
Aug 16, 2026
Merged

docs(contributing): state the bar — documentation standard, gates, tests-first#299
eaitbrahim merged 1 commit into
mainfrom
docs/contributing-standard

Conversation

@eaitbrahim

Copy link
Copy Markdown
Contributor

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

  • The documentation standard, taught from a worked example: the _open_exposure_by_asset
    docstring in keel/execution/guards.py is quoted in full, then dissected on the three
    properties that make it acceptable — it says why, it names what was measured, and it
    says what it would take to change the decision.
  • Dev setup and the gates: 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 gate
    nobody runs.
  • Tests first, with evidence: failing tests shown to fail for the right reason — an
    assertion, not an import error — carried in the PR.
  • Conventional Commits, matching history; the prefix is load-bearing for releases.
  • Three-tier scope: welcome / discuss-first (rails, default classifications, new deps,
    keel-broker-api surface) / out of scope (rulings as defaults, "make the bot profitable",
    weakening fails-closed paths).
  • The honest-upfront framing the issue asks for: the bar is high, said so at the top, with
    why.
  • Governance (rulings vs. machinery) and licence sections from Phase 6 kept intact.

Tests (tests/test_contributing.py, red first): gates stated verbatim; the worked
example 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: pytest 2788 passed / 1 skipped, ruff check clean, mypy clean.

…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.
@eaitbrahim
eaitbrahim merged commit 1ad4f9a into main Aug 16, 2026
1 check passed
@eaitbrahim
eaitbrahim deleted the docs/contributing-standard branch August 16, 2026 22:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Write CONTRIBUTING.md, including the documentation standard

1 participant