Skip to content

Write CONTRIBUTING.md, including the documentation standard #282

Description

@eaitbrahim

This repository has an unusually high documentation standard: decisions carry their reasoning, including why the alternatives were rejected, and comments record what was measured rather than what was assumed. It is the project's signature — and its single biggest barrier to contribution, because nobody will guess it.

Without stating it, PRs will arrive at ordinary quality, get heavy review, and the contributor will quietly leave. That is the most common way a promising project loses its first ten contributors.

Acceptance

  • CONTRIBUTING.md at repo root
  • The documentation standard, stated with a worked example — take an existing comment from guards.py or market_feed.py and show what makes it acceptable: it says why, it names what was measured, it says what it would take to change the decision
  • Dev setup: uv sync --all-extras --dev, and the gates a PR must pass — ruff check, mypy, pytest -q (currently 2,762 tests)
  • TDD expectation: tests first, and evidence in the PR that they failed for the right reason before the fix
  • Commit convention (Conventional Commits, matching existing history)
  • Scope guidance: what is welcome, what needs discussion first (anything touching a rail or a default classification), what is out of scope
  • The "not a fatwa engine" boundary from Phase 6, framed as PR scope

Note

Be honest that the bar is high and say why — people will meet a stated bar and resent an unstated one.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationopen-sourceWork toward making keel genuinely open sourceprerequisiteBlocks other issues; do first

Type

No type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions