Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
103 lines (72 loc) · 3.32 KB

CONTRIBUTING.md

File metadata and controls

103 lines (72 loc) · 3.32 KB
Raw

Contributing to EVMX

Thank you for considering contributing to EVMX. This project is built on a single, unbroken rule, and every contribution — code, review, or question — is measured against it first:

"We do not know" is never collapsed into "there is nothing."

That rule governs verdicts, and it governs pull requests. If a change could collapse a known uncertainty into a false certainty, it does not land.

Before you start

  • Read the project map — it is the external memory of the project. A decision that is not recorded there is treated as not made.
  • Read the README for the design contract (three outcomes, five evidence pieces, provenance-as-result).
  • Check the existing issues for open work before opening a new one.

Pull requests are the only way in

The default branch is protected. No one — including maintainers — pushes to it directly. Changes land only through a pull request that has passed review.

  1. Fork the repository (or create a feature branch).
  2. Use a branch named after what it changes, e.g. feat/third-network or fix/r5-stale-read.
  3. Open a pull request against the default branch.
  4. Await at least one approving review before merge.

Before you open a PR, verify

cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings

Green on all three is the entry standard — these are exactly the gates enforced by the CI workflow (see .github/workflows/ci.yml).

What a good PR looks like

  • One problem per PR. A small, focused change is easier to verify than a large one, and easier to hold to the project's bar.
  • Evidence with the code. If the change alters a detector or an invariant, say what the old and new behaviour are, and which tests demonstrate both.
  • Do not manufacture certainty. If the change fixes a gate by assuming a fact the corpus does not establish, it will be rejected.
  • Update the docs when you change the architecture. A design decision that is not in PROJECT_MAP.md is not a decision.

Tests

The offline suite (351 tests, no network) must stay green. Live-network tests exist and are #[ignore]d by default:

# run everything except live-network probes
cargo test --workspace

# run only the offline suite, explicitly
cargo test --workspace -- --skip probe_

Two conventions matter:

  • A test whose result depends on network conditions tests the network, not the code — it belongs in a #[ignore]d probe, not the offline suite.
  • Guards are proven by mutation: a guard that no test can break is not a guard. If your change touches a guard, the mutation of that guard must fail a test.

Issue reports

Use the issue templates where available. A good report includes:

  • What you did.
  • What you expected, phrased as evidence (the verdict, the named grounds).
  • What you got, verbatim.
  • The trace/fixture identifiers if relevant.

Licensing

By contributing, you agree that your contribution is licensed under the project's dual license (Apache-2.0 OR MIT), consistent with the repository's terms.

If you have questions about the contribution model, open a discussion rather than silently changing the bar.