House Conventions

Important

The pages below record design rulings for pcapkit – decisions that are not derivable from the code, and that a future maintainer or an automated contributor would otherwise have to rediscover by reading a closed issue thread. Each ruling names where it was settled.

What each page governs:

• Minting an Unrecognised Value – pcapkit.const, which is where the settled questions have mostly arisen;

• Naming a Sentinel – pcapkit.corekit;

• The Registry Protocol – pcapkit.const again;

• Extension-Header Base Classes – a protocol class hierarchy;

• 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.

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

• Minting an Unrecognised Value
• Naming a Sentinel
• The Registry Protocol
• Extension-Header Base Classes
• Protocol Layer Placement
• Running the Repository
• Writing the Documentation
• Testing a Change
• Choosing Between utilities and corekit