Skip to content

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 its AGENTS.md.
  • Copy config/.clang-format and config/.clang-tidy into _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.

  1. A change that alters a decision gets a new ADR in adr/ (or supersedes an existing one) in the same PR.
  2. The PR updates every page the change touches, including the checklists and the configs.
  3. 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