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:
- A distinct dependency set that is heavy or security-sensitive enough that a consumer should choose it on purpose.
- A consumer today, in pykit, kiln or a real application, not an expected one.
- 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
.importlinterforbidden 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'stransferextra imports Excel code but does not declarern-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).