How to contribute
The full guide is CONTRIBUTING.md at the root of the repository. This page summarises it and covers how to write documentation.
The feature workflow
Section titled “The feature workflow”Every security-relevant feature follows the same loop:
- Read the spec: the RFC, NIST or W3C document, plus the matching OWASP cheat sheet.
- Write the threat model: what an attacker controls, and what must never happen.
- Write the attacks as tests: each threat becomes a test that fails if the defence is missing.
- Implement it.
- Map it to OWASP ASVS in the pull request description.
Security issues must not be reported publicly. See SECURITY.md in the repository.
Branches, pull requests and commits
Section titled “Branches, pull requests and commits”- Every change starts with an issue. Branches are named
ISSUE-XXXX/TYPE/short-descriptive-title, for exampleISSUE-0001/FEATURE/adding-python-adaptor-X-endpoint. Pull request titles are Conventional Commits, for examplefeat(python): add the X endpoint. - Every commit follows Conventional Commits, such as
feat(core): rotate the session ID on privilege change, and makes one logical change. - New code goes where the directory conventions say.
make branchandmake commitwalk you through both.make hooksruns fmt and clippy and checks commit messages as you commit, adds cargo-deny before each push, and CI checks them on every pull request.
Writing API docs
Section titled “Writing API docs”The API reference is generated from doc comments, so writing doc comments is how you document the API. Every public item needs one.
Most of the API is defined in Rust, and its /// comments flow into all three references: rustdoc renders them, napi-rs copies them into the TypeScript declarations, and PyO3 turns them into Python docstrings. Code written directly in TypeScript uses TSDoc, and code written directly in Python uses Google-style docstrings.
Documentation standards
Section titled “Documentation standards”The full rules for writing documentation, including style, rules for examples, site pages and doc comments, are in docs/README.md in the repository. Read them before changing any documentation.
