Skip to content

Repository

What every repository contains and declares.

Rule Level Applies to Verified
KB-REPO-001 Required root files must all checked
KB-REPO-002 Each repository declares the handbook version, kind and level it follows must all checked
KB-REPO-003 Waivers name a rule, a reason, an approver and an expiry must all checked
KB-REPO-004 Every source file carries an SPDX licence identifier should driver, library, hal, firmware, tooling, template planned
KB-REPO-005 The root holds only the entries listed for the repository's kind must all checked
KB-REPO-006 A driver has the driver layout must driver, template checked
KB-REPO-007 File names follow the layer's convention should driver, library, hal, template planned
KB-REPO-008 A standalone library starts from driver-template and keeps its layout must library checked
KB-REPO-009 kb-core keeps its monorepo layout must library checked
KB-REPO-010 A board HAL has the board HAL layout must hal checked
KB-REPO-011 A product has the product layout must firmware checked
KB-REPO-012 Board HALs and products live in the product's organisation guide hal, firmware review
KB-REPO-013 Each example platform stands alone, and sources have one home should driver, library, template checked
KB-REPO-014 No symlinks anywhere in a repository must all planned
KB-REPO-015 _config/ holds the org's tool configs unchanged, and tools are pointed at it must driver, library, hal, firmware, template planned
KB-REPO-016 ESP-IDF projects commit sdkconfig.defaults, never sdkconfig must driver, library, hal, firmware, template checked
KB-REPO-017 No ESP-IDF wrapper component or idf_component.yml unless the registry is chosen should driver, library, template planned
KB-REPO-018 Every driver declares itself in driver.yml must driver, template checked
KB-REPO-019 Third-party code keeps its own licence under third_party/ must all planned
KB-REPO-020 Hardware is CERN-OHL-P-2.0; a product owner picks the board HAL licence should all review
KB-REPO-021 CODEOWNERS gives every path a default owner should all planned
KB-REPO-022 Vulnerabilities are reported privately, as SECURITY.md says must all planned
KB-REPO-023 Issues use the org forms and labels should all planned
KB-REPO-024 Repository settings are code in the .github repository must all checked
KB-REPO-025 A new repository starts from its kind's template and is declared first should all review
KB-REPO-026 A superseded repository is marked legacy and archived should all review
KB-REPO-027 CubeMX code is committed with the .ioc it came from should hal, firmware review

KB-REPO-001: Required root files

MUST · all · since 1.0

Every repository has README.md, LICENSE (MIT for code), CHANGELOG.md and .github/CODEOWNERS at its root.

Verified by:

  • org-standard-files (implemented): README.md, LICENSE (MIT), CHANGELOG.md and .github/CODEOWNERS exist

See also: ADR-0009; ADR-0011

KB-REPO-002: Each repository declares the handbook version, kind and level it follows

MUST · all · since 1.0

.kokeb/handbook.yml names a released handbook version, the repository's kind and its assurance level, and lists its waivers.

Verified by:

  • handbook-declaration (implemented): .kokeb/handbook.yml exists and names a released handbook version, a kind and a level

Explained in: how-rules-work.md

KB-REPO-003: Waivers name a rule, a reason, an approver and an expiry

MUST · all · since 1.0

A rule is set aside only by a waiver in .kokeb/handbook.yml that names the rule ID, why, who approved it and the date it expires. An expired waiver fails CI.

Verified by:

  • waivers (implemented): every waiver names an existing rule, a reason, an approver and an expiry date that has not passed

Explained in: deviations.md

KB-REPO-004: Every source file carries an SPDX licence identifier

Proposed

Not enforced yet.

SHOULD · driver, library, hal, firmware, tooling, template · since 1.0

Each source file starts with SPDX-License-Identifier: and a copyright line, as REUSE checks it.

Verified by:

  • spdx-headers (planned): every source file carries an SPDX licence identifier (REUSE)

KB-REPO-005: The root holds only the entries listed for the repository's kind

MUST · all · since 1.0

Tool configuration lives in _config/, not at the root. An extra root file a tool insists on is listed, with the tool, in AGENTS.md; a pull request adding a root entry without such a reason is refused.

Verified by:

  • repo-layout (implemented): the committed root entries match the layout for the repository's kind (drivers and templates today)

See also: ADR-0011

Explained in: standards/repo-governance.md

KB-REPO-006: A driver has the driver layout

Proposed

Warns until 2027-03-01, then fails CI. driver-template's self-test checks part of it, in the template only.

MUST · driver, template · since 1.0 · enforced from 2027-03-01

A driver keeps inc/<chip>.hpp, inc/<chip>_<bus>_interface.hpp, inc/<chip>_types.hpp, src/<chip>.ipp, cmake/, examples/host/ and other platforms, a flat tests/, docs/ and _config/.

Verified by:

  • repo-layout (implemented): the committed root entries match the layout for the repository's kind (drivers and templates today)

See also: ADR-0011; ADR-0012

Explained in: standards/driver.md

KB-REPO-007: File names follow the layer's convention

Proposed

Warns until 2027-03-01, then fails CI.

SHOULD · driver, library, hal, template · since 1.0 · enforced from 2027-03-01

Driver files are <chip>_<part>.hpp and .ipp; kb-core and board HAL files are PascalCase .h and .cpp named for the class they hold; tests are test_<subject>.cpp.

Verified by:

  • file-names (planned): source and test file names match the pattern for the repository's kind

See also: ADR-0008

Explained in: standards/naming-and-style.md

KB-REPO-008: A standalone library starts from driver-template and keeps its layout

Proposed

Warns until 2027-03-01, then fails CI. kb-core has its own layout (KB-REPO-009).

MUST · library · since 1.0 · enforced from 2027-03-01

A library outside kb-core is generated with driver-template --kind library and keeps the driver root layout, an examples/host/, one CMake target and one include root.

Verified by:

  • repo-layout (implemented): the committed root entries match the layout for the repository's kind (drivers and templates today)

See also: ADR-0011

Explained in: standards/library.md

KB-REPO-009: kb-core keeps its monorepo layout

Proposed

Warns until 2027-03-01, then fails CI. Applies to kb-core only.

MUST · library · since 1.0 · enforced from 2027-03-01

kb-core holds utils/, rtos/, interfaces/ (base, mcu/<family>/, host), handlers/, drivers/ with one submodule per driver, cmake/kb_build_settings.cmake and catalog/compat.yml.

Verified by:

  • repo-layout (implemented): the committed root entries match the layout for the repository's kind (drivers and templates today)

See also: ADR-0013

Explained in: standards/library.md

KB-REPO-010: A board HAL has the board HAL layout

Proposed

Warns until 2027-03-01, then fails CI.

MUST · hal · since 1.0 · enforced from 2027-03-01

A board HAL has lib/common (kb-hal-common) and lib/core (kb-core) submodules, one board/<board>/ folder of bus, chip and pin tables (data, not logic), a bsp_bind/<family>/ per family plus bsp_bind/host/, and _config/. Its only root extras are CMakePresets.json and version_lock.txt.

Verified by:

  • repo-layout (implemented): the committed root entries match the layout for the repository's kind (drivers and templates today)

See also: ADR-0005; ADR-0011

Explained in: standards/hal.md

KB-REPO-011: A product has the product layout

Proposed

Warns until 2027-03-01, then fails CI. Examples and test benches of the firmware kind are exempt.

MUST · firmware · since 1.0 · enforced from 2027-03-01

A product holds main/ (or app/), platform/, hal/, version_lock.txt, sdkconfig.defaults, partitions.csv, docs/ and _config/.

Verified by:

  • repo-layout (implemented): the committed root entries match the layout for the repository's kind (drivers and templates today)

See also: ADR-0011

Explained in: standards/product.md

KB-REPO-012: Board HALs and products live in the product's organisation

GUIDE · hal, firmware · since 1.0

kokeb-labs holds reusable code only. A board HAL or product lives in its product's organisation (HardFOC is one) and starts from the board HAL template.

Verified by:

  • review: A new board HAL or product repository is created in the product organisation.

See also: ADR-0005

Explained in: standards/hal.md

KB-REPO-013: Each example platform stands alone, and sources have one home

Proposed

Warns until 2027-03-01, then fails CI.

SHOULD · driver, library, template · since 1.0 · enforced from 2027-03-01

Every examples/<platform>/ has its own port, example program and README and builds on its own. Zephyr, Arduino or PlatformIO manifests are added only when a user needs them, and never copy the sources.

Verified by:

  • repo-layout (implemented): the committed root entries match the layout for the repository's kind (drivers and templates today)
  • review: Any extra ecosystem manifest points at the existing sources.

Explained in: standards/driver.md

KB-REPO-014: No symlinks anywhere in a repository

Proposed

Warns until 2027-03-01, then fails CI. driver-template's self-test scans for symlinks in the template only.

MUST · all · since 1.0 · enforced from 2027-03-01

A repository tracks no symbolic links. An editor that wants a config at the root gets a local, gitignored copy of the file in _config/.

Verified by:

  • tracked-files/symlinks (planned): git tracks no file of a banned kind; the parameter names it (tracked-files/symlinks, tracked-files/sdkconfig, tracked-files/idf-component)

See also: ADR-0011

Explained in: standards/repo-governance.md

KB-REPO-015: _config/ holds the org's tool configs unchanged, and tools are pointed at it

Proposed

Warns until 2027-03-01, then fails CI. ci-tools' own _config/ clang configs, the ru-cpp-lint defaults, differ from the handbook's and need the same fix.

MUST · driver, library, hal, firmware, template · since 1.0 · enforced from 2027-03-01

_config/.clang-format and _config/.clang-tidy are byte copies of the handbook's config/ files, apart from the header comment. Every command and workflow passes the _config/ path to its tool.

Verified by:

  • config-drift (planned): _config/.clang-format and _config/.clang-tidy equal the handbook's config/ files apart from the header

See also: ADR-0008; ADR-0011

Explained in: standards/naming-and-style.md

KB-REPO-016: ESP-IDF projects commit sdkconfig.defaults, never sdkconfig

MUST · driver, library, hal, firmware, template · since 1.0

The settings an ESP-IDF project needs are in sdkconfig.defaults (and sdkconfig.defaults.<target>); the generated sdkconfig is gitignored and never committed. A firmware release attaches the effective sdkconfig instead.

Verified by:

  • tracked-files/sdkconfig (implemented): git tracks no file of a banned kind; the parameter names it (tracked-files/symlinks, tracked-files/sdkconfig, tracked-files/idf-component)

See also: ADR-0018

Explained in: standards/driver.md

KB-REPO-017: No ESP-IDF wrapper component or idf_component.yml unless the registry is chosen

Proposed

Warns until 2027-03-01, then fails CI.

SHOULD · driver, library, template · since 1.0 · enforced from 2027-03-01

A driver or library has no wrapper component folder and no idf_component.yml, unless a decision record chooses to publish it to the ESP Component Registry.

Verified by:

  • tracked-files/idf-component (planned): git tracks no file of a banned kind; the parameter names it (tracked-files/symlinks, tracked-files/sdkconfig, tracked-files/idf-component)

See also: ADR-0007; ADR-0011

Explained in: standards/driver.md

KB-REPO-018: Every driver declares itself in driver.yml

MUST · driver, template · since 1.0

A driver's root driver.yml gives its name, version, bus, supported MCUs, peripheral and minimum kb-core version, and CI checks it against the build settings and the examples it builds.

Verified by:

  • driver-manifest (implemented): driver.yml exists, validates against its schema, and its version, MCUs and examples match the build settings and the examples folder

See also: ADR-0007; ADR-0011

Explained in: standards/driver.md

KB-REPO-019: Third-party code keeps its own licence under third_party/

Proposed

Warns until 2027-03-01, then fails CI. ADR-0011's root list does not yet include third_party/.

MUST · all · since 1.0 · enforced from 2027-03-01

Code copied in from elsewhere is MIT-compatible and sits in third_party/<name>/ with its original licence and notice. It is never mixed into the repository's own sources.

Verified by:

  • third-party-licences (planned): every third_party/<name>/ has a licence file, and REUSE or scancode finds only MIT-compatible licences

See also: ADR-0009; IEC 62304:2006+A1:2015 8.1 (SOUP identification)

Explained in: standards/repo-governance.md

KB-REPO-020: Hardware is CERN-OHL-P-2.0; a product owner picks the board HAL licence

SHOULD · all · since 1.0

Hardware designs are licensed CERN-OHL-P-2.0. A board HAL in a product organisation carries the licence its product owner chooses in LICENSE. No licence grants use of the Kokeb Labs name or logos.

Verified by:

  • review: LICENSE, README badges and package manifests name the same licence.

See also: ADR-0009

Explained in: standards/repo-governance.md

KB-REPO-021: CODEOWNERS gives every path a default owner

Proposed

Warns until 2027-03-01, then fails CI. org-standard-check confirms only that the file is not empty.

SHOULD · all · since 1.0 · enforced from 2027-03-01

.github/CODEOWNERS starts with a * line naming the maintainer (@N3b3x, later @kokeb-labs/maintainers), so every path has an owner.

Verified by:

  • codeowners (planned): .github/CODEOWNERS has a * rule naming at least one owner

See also: ADR-0015

Explained in: standards/repo-governance.md

KB-REPO-022: Vulnerabilities are reported privately, as SECURITY.md says

MUST · all · since 1.0

SECURITY.md and CONTRIBUTING.md live in .github/ or are inherited from the organisation. A vulnerability is reported through a private security advisory, never a public issue.

Verified by:

  • security-policy (planned): SECURITY.md exists in .github/ or is inherited from the organisation and names private reporting
  • review: A vulnerability reported in public was moved to a private advisory and the issue hidden.

See also: ADR-0015; IEC 62304:2006+A1:2015 9 (problem reports)

Explained in: standards/repo-governance.md

KB-REPO-023: Issues use the org forms and labels

SHOULD · all · since 1.0

Issues are opened with the organisation's Bug, Driver request or Feature forms, blank issues are off and questions go to Discussions. Every repository uses the org label set (bug, enhancement, safety, breaking, …).

Verified by:

  • org-settings-drift (planned): a scheduled kokeb_org.py --check finds no drift between org/ and the repository's live settings
  • review: The repository adds no issue templates or labels of its own outside org/labels.json.

See also: IEC 62304:2006+A1:2015 9 (problem reports are classified)

Explained in: standards/repo-governance.md

KB-REPO-024: Repository settings are code in the .github repository

MUST · all · since 1.0

Merge settings, rulesets, security features, labels, description, homepage and topics are declared in kokeb-labs/.github org/, changed by pull request, and applied by an organisation owner with kokeb_org.py --apply.

Verified by:

  • rulesets (implemented): branch and tag rulesets as declared in .github/org/rulesets (PR only, linear history, tags kept)
  • org-settings-drift (planned): a scheduled kokeb_org.py --check finds no drift between org/ and the repository's live settings
  • review: The setting was changed in org/ by pull request, not in the GitHub UI.

See also: ADR-0015; IEC 62304:2006+A1:2015 8.2 (controlled changes to the environment)

Explained in: standards/repo-governance.md

KB-REPO-025: A new repository starts from its kind's template and is declared first

SHOULD · all · since 1.0

A repository is added to org/repos.json by pull request, then created public from its kind's template (drivers and libraries through tools/setup.py) and follows the kind's checklist.

Verified by:

  • review: The repository is in org/repos.json and was generated from its kind's template.

Explained in: standards/repo-governance.md

KB-REPO-026: A superseded repository is marked legacy and archived

SHOULD · all · since 1.0

When a repository is replaced, it gets the legacy topic, a [Legacy] description and a README note naming its successor, and is then archived.

Verified by:

  • review: The archived repository's topic, description and README name its successor.

Explained in: standards/repo-governance.md

KB-REPO-027: CubeMX code is committed with the .ioc it came from

SHOULD · hal, firmware · since 1.0

Generated STM32CubeMX code is committed together with its .ioc project, so a reviewer can regenerate it and diff. Both sit under the family's bsp_bind/<family>/, not at the root.

Verified by:

  • review: The .ioc in the pull request regenerates exactly the generated code it carries.

Explained in: standards/hal.md