ADR-0019: Datasheets are referenced by exact revision, never committed¶
- Status: Accepted
- Date: 2026-11-06
Context¶
The new-driver checklist said to store the datasheet in docs/datasheet/ "where its licence allows", while the
driver template, the pull-request template and the agents page say no vendor PDF is committed. Vendor licences
rarely allow redistribution and change over time, and a repository cannot tell which licence applied when a file
was added. What reviewers and auditors actually need is to know exactly which revision the code was written
against.
Decision¶
- No datasheet, reference manual or application note is committed to a Kokeb Labs repository.
tracked-files/datasheetsfails CI on a tracked PDF underdocs/that is listed as vendor documentation. - Each driver lists the documents it was written against in
docs/datasheets.yml: vendor, title, document number, revision, date, the vendor's URL, and the SHA-256 of the PDF that was used. The hash lets anyone confirm they hold the same revision without the repository redistributing it. - Code comments cite a datasheet by document number, revision and section (KB-CPP-111).
Consequences¶
- The new-driver checklist and rule KB-DOC-035 change to the reference model.
- For a safety-level component the list is part of the evidence package: it identifies the source of every register value and timing in the requirements.