House Conventions¶

Important

The pages below record design rulings for pcapkit: decisions not derivable from the code, which a maintainer or an automated contributor would otherwise rediscover from a closed issue thread. Each ruling names where it was settled.

What each page governs:

Minting an Unrecognised Value – pcapkit.const;
Naming a Sentinel – pcapkit.corekit;
The Registry Protocol – pcapkit.const again, the registration wrappers of pcapkit.foundation.registry, how a make() field holding an enumeration resolves, and the value a protocol’s __index__() returns;
Extension-Header Base Classes – a protocol class hierarchy;
Protocol Family Grouping – how a protocol family’s base and members spell id(), how a protocol’s package, modules and classes are named and imported, and how quietly a next-layer fallback keeps a refused layer as Raw;
Protocol Member Order – the order of members in a protocol class body;
Protocol Layer Placement – which subpackage a dissector belongs in;
Running the Repository – the repository rather than any of its code;
Writing the Documentation – the prose itself, on these pages and in the API reference, rather than any code at all;
Testing a Change – what the test suite has to prove;
Choosing Between utilities and corekit – which of pcapkit.utilities and pcapkit.corekit a support module belongs in, where a context variable lives, where a schema helper used outside the schema layer or outside its own protocol lives, and what reads a capture cut;
Reassembly Integration – pcapkit.foundation.reassembly and what a new engine there needs from pcapkit.toolkit and pcapkit.foundation.analysis;
Const-Vendor Pairing – pcapkit.const, the pcapkit.vendor crawler each module needs, and how a package of it imports its modules.

A ruling that stays in its thread is a ruling that gets rediscovered. So a question answered in a way the code cannot express on its own – a classification, a naming rule, a deliberate asymmetry – is written onto the page that covers it in the same change that implements it, on the owner’s standing ask on #918.