Skip to content

ADR-0011: A part of commons becomes its own package only when it passes three tests, and every package takes adapters the same way

Status: accepted (2026-10-15) · Scope: creating packages out of rn-forge-commons, and how a package holds its optional integrations

Decision

A part of rn-forge-commons becomes its own package only when it passes all three tests:

  1. A distinct dependency set that is heavy or security-sensitive enough that a consumer should choose it on purpose.
  2. A consumer today, in pykit, kiln or a real application, not an expected one.
  3. One audience: the people who install it want all of it, so it needs few extras of its own.

A part that fails any test stays in commons, behind an extra if it has dependencies.

A package that integrates with external systems has one structure:

  • Its core holds protocols, data types and neutral logic, with no third-party dependency beyond its rn-forge base.
  • Each adapter is its own module or subpackage, rn_forge.<pkg>.<adapter>, behind an extra named after it.
  • The core never imports an adapter. An .importlinter forbidden contract enforces it. Adapters import the core.
  • The curated __init__ facade re-exports the core only. Adapter modules are imported directly (ADR-0003).
  • A framework package binds a package through its own extra that names rn-forge-<pkg>[<adapter>], never a list of commons extras.

Adding an adapter is a new module, a new extra, a docs page and tests. It does not change the core's public API.

Consequences

rn-forge-auth and rn-forge-data pass the tests now. integration/resilience, messaging, logging and the fs, lang and runtime helpers do not, and stay in commons.

Each package costs a tag and pin (ADR-0004), a CI verify job, a MkDocs site, a changelog, a slot in the release batch, a pin bump in every consumer on each release, and an entry in kiln's archetype allowed lists. The tests exist to keep that cost for parts that need it.

Moving code across a package boundary is a breaking release of the packages that lose and gain it, because ADR-0002 forbids aliases. A new adapter is not breaking.

The structure costs one forbidden contract per package, and a convention that every adapter module maps to an extra of the same name.

Influences

E15 and its design apply this rule. E13's package placement is its first use. It refines ADR-0002 on placement and ADR-0003 on extras.

Alternatives considered

  • A broad split of commons into many packages. The base install is five small libraries, and importing commons loads no optional one, so a split would remove no install weight. It would multiply pins and release slots for parts every package uses together.
  • Everything stays a commons extra. Framework packages then keep a list of commons extras that they must keep in sync. This already failed once: rn-forge-django's transfer extra imports Excel code but does not declare rn-forge-commons[excel], and works only because another dependency installs openpyxl.
  • Adapters inside the core module. A core that imports its adapters needs their libraries to import at all, so no adapter can be optional.

Background

Proposed on 2026-10-13 from the owner-approved package-split analysis. The owner accepted it on 2026-10-15 (S15.1.1).