Kokeb Labs engineering standard¶
The rules every Kokeb Labs repository follows: how each layer is shaped, what it may depend on, how errors, threads and time work, how code is named and formatted, and how repositories are governed, documented and released.
This directory is the single source of truth. Repository docs, templates, CI configuration and agents link here instead of restating it. When a repository and this standard disagree, the standard wins, and the repository gets an issue.
The standard lives at https://github.com/kokeb-labs/.github/tree/main/standards.
How to read it¶
The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY mean what RFC 2119 says they mean. A MUST is checked in review or CI. A SHOULD can be broken for a reason that the PR states.
Each rule applies to new code at once. Existing code converges through the order of work in the decision records: a repository that does not meet a rule yet is tracked by an issue, not exempted.
Contents¶
Layer contracts¶
| Page | Covers |
|---|---|
| Layers | The stack, what each layer promises and depends on, allowed and forbidden includes, the three kinds of "specific" |
| Driver | driver-<chip>: port, Result<T>, Error, lifecycle, config, memory, build, driver.yml, tests |
| Library | kb-core's utils, rtos and interfaces, how kb-core builds, and standalone libraries such as pincfg |
| Handler | kb-core/handlers/<chip>: one handler family, adapters, VisitDriver, diagnostics |
| Board HAL | Board HALs, the shared kb-hal-common and bsp_bind/<family> |
| Product | Product applications, which live in product organizations |
Cross-layer rules¶
| Page | Covers |
|---|---|
| Errors | kb::Status, kb::Result<T> and the mapping at each layer boundary |
| Threading and timing | One lock, one clock, one delay; the 1 kHz FreeRTOS tick |
| C++20 profile | Which C++20 features we use, use with rules or forbid, as guidelines KB-CPP20-001 to 058 with their enforcement; what MD-CPP-001 covers |
| Naming and style | Names, units, namespaces, include roots, and the org .clang-format and .clang-tidy |
Process¶
| Page | Covers |
|---|---|
| Repository governance | Branches, PRs, DCO, labels, CODEOWNERS, rulesets, required checks, security, trademarks, new repositories |
| Release | SemVer 0.x, release candidates, release trains, prepare-release, changelog rules, bottom-up release order |
| Documentation | The page set, the Contract page, Doxygen settings, README sections |
| Agents | How coding agents work in Kokeb Labs repositories: AGENTS.md, skills, definition of done |
Records and checklists¶
| Page | Covers |
|---|---|
| Architecture decision records | Why the rules are what they are, one decision per record |
| New driver | Copyable checklist for a new driver-<chip> |
| New handler | Copyable checklist for a new handler in kb-core |
| New board HAL | Copyable checklist for a new board HAL |
| Release | Copyable checklist for one repository's release |
Using the standard in a repository¶
- Link the standard from the repository's
CONTRIBUTING.md(or rely on the org default) and from itsAGENTS.md. - Copy
config/.clang-formatandconfig/.clang-tidyinto_config/unchanged. A repository MUST NOT carry local edits to them; propose the change here. All other tool configuration lives in_config/too, and the root follows ADR-0011. - When a PR deviates from a MUST, say so in the PR description, name the rule, and link the issue that tracks the fix. A reviewer can refuse the deviation.
- Start new repositories from the templates and the checklists; the checklists are the standard condensed into steps.
Changing the standard¶
The standard changes by pull request to kokeb-labs/.github, like code.
- A change that alters a decision gets a new ADR in
adr/(or supersedes an existing one) in the same PR. - The PR updates every page the change touches, including the checklists and the configs.
- Once it merges, open issues in the repositories that no longer comply.
Editorial fixes (wording, links, examples that do not change a rule) need no ADR.
Fixed decisions¶
These are not reopened without a superseding ADR:
| Decision | Record |
|---|---|
Drivers keep their own <chip>::Error and Result<T>; handlers map them to kb::Status / kb::Result<T> |
ADR-0001 |
One lifecycle: I/O-free constructor, Initialize() with a chip-ID check, EnsureInitialized() |
ADR-0002 |
| Drivers are templates on a CRTP port; no virtual calls below the handler | ADR-0003 |
| No heap after start-up; none at all in drivers | ADR-0004 |
A shared kb-hal-common repository for what board HALs have in common |
ADR-0005 |
| FreeRTOS runs at 1 kHz everywhere | ADR-0006 |
| Drivers pinned in kb-core to release tags; tested sets released as trains | ADR-0007 |
One naming scheme, enforced by clang-tidy |
ADR-0008 |
| MIT for firmware and tooling; CERN-OHL-P-2.0 for hardware designs | ADR-0009 |
| C++20 in every repository | ADR-0010 |
The root holds only required and first-read files; tool configuration in _config/, no symlinks; one root CMakeLists.txt for CMake and ESP-IDF; platform code only in examples/<platform>/ |
ADR-0011 |
Drivers carry no brand: driver-<chip>, namespace <chip>, <chip>::<chip> |
ADR-0012 |
| kb-core is one monorepo with four targets and one version | ADR-0013 |
| Chip-, MCU- and product-specific code each have one place; shared code never tests a platform macro | ADR-0014 |
| Governance for one maintainer open to contributors: squash, linear, signed, DCO | ADR-0015 |