Adding a package
This runbook guides maintainers through adding a pykit workspace member. It covers repository integration; the package's own README and docs own its API and setup.
- Give the package its own
packages/<name>/pyproject.toml,src/rn_forge/<module>/tree,py.typedmarker, tests, README,CHANGELOG.md, documentation and standalonemkdocs.yml. Follow the existinguv_buildnamespace package mapping and Python floor. Copy the published-package parts from an existing package (ADR-0009):[project.urls], the README's opening links line and its absolute-only links,docs/changelog.mdwith its nav entry, and themkdocs.ymlsite_url,repo_url,pymdownx.snippets,mikeplugin (canonical_version: latest) andextra.version.provider: mikesettings. - Copy
LICENSEfrom the repository root intopackages/<name>/, and thelicense,license-filesandclassifiersblock from an existing member'spyproject.toml(adding the package'sFramework ::classifier, if it has one). The release build failstwine check --strictwithout them. - Add the member to root
[tool.uv.workspace].membersand the root development dependency group. Add local[tool.uv.sources]overrides for its internal dependencies while declaring the dependencies by version range (task ci:internal-rangeschecks that). Inspect optional extras independently. - Update the root
.importlinterfile with the new package's place in the graph. Keep the import rules executable before adding cross-package imports. The workspace page describes the current boundaries. If the package takes adapters (ADR-0011), each adapter module maps to an extra of the same name. List the names in[tool.workspace-ci] adapters; CI checks the mapping withtask ci:adapters. One forbidden contract per package keeps the core from importing its adapters. - Add the package to the root MkDocs includes and reader entry points. Build its standalone site and the combined site with strict link checking.
- CI picks the member up from the workspace
(F14.1);
the workflow needs no edit. If the package has PostgreSQL tests or extras
that need an isolated install check, declare them in its
[tool.workspace-ci]tables, asrn-forge-djangodoes. The docs job publishes the package's versioned site when its first tag is cut (F9.9). - Validate the new package's tests, lint, types, import contracts and documentation. A local workspace build does not show that the package installs outside the workspace; a release proves that (releasing packages).
If applications will install the package, add a scaffolded-application test for it, as F9.8 does for the existing packages (ADR-0008).