Developing pykit
The workspace's local setup and validation commands. Run them from the repository root unless a command says otherwise.
Setup
The repository is a uv workspace with ten packages. Install every package with
its dev and docs dependency groups, which bring each package's optional
extras, with:
Package code targets Python 3.14 or later, and the floor stays at >=3.14
across the workspace; lowering it would be a workspace decision, not a package
one. Use a patch release: on a 3.14 release candidate, mkdocstrings' pydantic
support fails
(_eval_type() got an unexpected keyword argument 'prefer_fwd_module') and
every docs build exits 1. Python 3.14.2 and later build cleanly.
Commands
Every gate is a task verb, run from the repository root.
| Check | Command |
|---|---|
| Install | task setup |
| All tests | task test |
| Lint: ruff, format check, import boundaries, Markdown and TOML formatting, dependency audit, licences | task lint |
| Format in place | task format |
| Strict type check | task typecheck |
| Combined documentation, root and every package, strict | task docs:build |
| Lint, type check, tests and documentation together | task validate |
| Regenerate the derived documentation regions | task docs:generate |
Broker profile (rn-forge-auth, needs Docker) |
task ci:integration -- rn-forge-auth |
A narrower run filters a run through task test and is not a gate:
task validate is the gate.
| Run | Command |
|---|---|
| One package's tests | task test PACKAGE_DIRS=packages/rn-forge-cli |
| One test file or test, by package-relative id | PYTEST_ADDOPTS='tests/test_command_paths.py::test_exit_codes' task test PACKAGE_DIRS=packages/rn-forge-cli |
| By keyword | PYTEST_ADDOPTS='-k test_name' task test PACKAGE_DIRS=packages/<pkg> |
Fast isolated tests (rn-forge-django, rn-forge-web) |
PYTEST_ADDOPTS='-m unit' task test PACKAGE_DIRS=packages/<pkg> |
Database-backed tests (rn-forge-django, rn-forge-sqlalchemy) |
task ci:integration -- <package> (needs Docker) |
The broker profile tests run against a Keycloak container and skip without
RN_FORGE_AUTH_KEYCLOAK_URL. CI runs them in the integration job of ci.yml,
against the keycloak service that rn-forge-auth declares in
[tool.workspace-ci.integration.keycloak]. The broker profile (rn-forge-auth,
needs Docker) runs as task ci:integration -- rn-forge-auth.
Dependency audit
task lint fails on a known vulnerability in uv.lock (pip-audit over
uv export --frozen, ADR-0015), and CI runs it in the
validate job. To accept a finding, add its advisory ID and the reason to the
ignore list of [ci.checks.pip-audit] in .rn-forge/kiln/config.toml, as
ignore = [{ id = "<ID>", reason = "<why, and when to revisit>" }], then run
task kiln:apply. An entry without a reason is not allowed.
task lint also fails on a dependency whose licence matches GPL, AGPL or
UNKNOWN, and allows LGPL. Workspace members are left out, so the check covers
third-party dependencies only. [ci.checks.licenses] in the same file sets
deny and ignore; a dual-licensed package used under its permissive option
goes in ignore, then task kiln:apply.
task lint also runs ruff's S rules (Bandit's checks, including the Django
ones) over the packages, and CI scans the full git history for secrets with
gitleaks (task ci:secret-scan), which is not part of task lint. Report a
vulnerability privately through GitHub private vulnerability reporting, as
SECURITY.md says.
Sonar feedback
Connect SonarQube for IDE to the project's SonarCloud server (connected mode) for instant rule feedback while editing. Taint analysis and the quality gate need a server analysis, which the IDE cannot certify.
To analyze the working tree before pushing:
The first command prints the target branch and the exact test and scanner commands; it needs no token and runs nothing. The second runs the workspace coverage tests, then uploads the code and results to SonarCloud and exits with the quality gate's status. A full scan needs:
- network access, and a non-
mainbranch on a plan with branch analysis; the verb refusesmain, and--branchmust match the checked-out branch unless HEAD is detached; - a SonarCloud token provided by the project owner, exported as
SONAR_TOKEN; - the official
SonarScanner CLI
on
PATH. The repository adds no dependency for it.
A scan of uncommitted changes is not CI evidence for a commit.
Dependabot pull requests
Bring a Dependabot pull request up to date with @dependabot rebase or GitHub's
"Update with rebase". Do not use "Update branch": it merges main into the
branch and puts a merge commit on main, which breaks its linear history.
Scorecard
.github/workflows/scorecard.yml runs OpenSSF Scorecard on pushes to main,
weekly and on demand. It reports only: the SARIF result goes to code scanning
and is kept as the scorecard-sarif artifact, and no score fails a build.
Documentation builds
Each package also has a standalone MkDocs site. task docs:build builds the
root site and then every package's own site, each with --strict: the root site
includes all ten, but a combined build does not show that each standalone site
resolves its own links, so the task checks both. task docs:build -- <dir>
writes the root site to <dir>, which keeps an existing preview.
Tests and types
Tests live under each package's tests/ tree. The root pytest configuration
uses importlib import mode and registers the unit, integration and
postgres markers. Source under packages/ is checked by Pyright in strict
mode; tests and two framework-specific web documentation examples are excluded,
while the framework-neutral ASGI example is checked.
For a new package, follow Adding a package. The workspace boundaries describe the import contracts it must respect.