Contributing

Fixes, tests, and improvements to the interface and documents are welcome. Before you start, confirm which layer your change belongs to.

Where a change goes

Process

1. Open an issue first, saying what you want to change and why; small corrections can go straight to a pull request.
2. Branch from main, one request per change.
3. Run every test locally.
4. In the commit message, say what changed and what users will see.

Checks before submitting

• cargo test --workspace passes.
• cargo build --release --locked passes; when dependencies are added or removed, commit Cargo.lock with the change.
• If zikaron or zikaron-kit changed: the comparer shows zero divergences on corpora from at least three seeds, generated in a copy outside the repository.
• If zikaron-anchor changed: every chain-facing recording replays identically.
• Both digests of the law and the contract’s code hash recompute to their values.
• Every new sentence in the interface exists in Chinese and English.
• Every new control is wired to a real action and shows a clear message when it fails.
• The matching passage of the manual is updated, Chinese and English matching sentence for sentence.

Judgment belongs in the cores

When interface code meets a question such as “is this entry valid” or “is this grant in force right now”, call the core and use its conclusion. A judgment rewritten in the interface will drift from the original. Likewise, the command line passes a core’s output on unchanged.

Rules for tests

Temporary directories

Every test creates its machine folder and data folder in its own temporary directory and clears it at the end.

Test keys

Keys are generated in the test or taken from the corpus; real recovery words and private keys stay outside the repository.

A local chain

Tests that touch anchoring run against a local anvil or recordings; public nodes are for manual trials.

Both sides

Every refusal rule comes with one input that should be refused and one that should be accepted.

Injected time

A test that needs “now” passes the moment in as an argument.

Interface conventions

• An action that writes to the ledger or the chain first opens a confirmation card listing where it writes, what it writes and the cost; the solid red key that actually writes appears on the confirmation card alone.
• A screen holds at most one blue primary button.
• The front of the interface uses plain language; addresses, hashes, type names and verdict tokens go under “Details”.
• Every failure says two things: what happened, and what to do next.
• Pages respond at once; long work runs in the background and announces itself once, on completion.
• Where the interface says “in effect” or “confirmed”, a readable fact stands behind it.

Wording

Interface wording follows the concise style of mature applications. The manual, the Wiki and this guide state what holds now; history stays in the version record. Code comments are in English and name the section when citing the law.

Keeping the repository clean

Commits hold product source and documents alone; local paths, e-mail addresses, keys, node access tokens and personal test data stay outside the repository. Read the diff before you commit.