Contributing¶

Working on the code¶

uv sync
make clean   # format + lint + typecheck (ruff, mypy)
make test    # pytest; the gate tests run real git worktrees, allow a few minutes
make docs    # generate the reference pages and build this site into site/
make docs-serve

Commit messages carry the Linear id: [KFF-123] Imperative summary. Everything under docs/reference/ is generated by scripts/gen_docs_reference.py from the code (click groups, pydantic models, the MCP server's tool list, the threat catalogue) and is not committed.

Releasing¶

The version is the git tag; pyproject.toml carries a 0.0.0 placeholder that the release workflow replaces before building. Write the version's section in CHANGELOG.md first, then:

git tag v1.2.3 && git push origin v1.2.3        # a release
git tag v1.2.3rc1 && git push origin v1.2.3rc1  # a release candidate

release.yml builds the wheel, smoke-tests model-wtf --version from it, publishes to PyPI through trusted publishing (the PyPI project trusts this repository's release.yml in the pypi environment; no token is stored), creates the GitHub release from the matching changelog section, and moves the v1 branch and tag so uses: ModelW/wtf@v1 follows the latest 1.x.

A candidate (rc, a, b) is published on PyPI and as a GitHub pre-release under the final version's changelog section, but does not move v1: try it with uses: ModelW/wtf@v1.2.3rc1 or pip install model-wtf==1.2.3rc1.