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
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)
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)
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
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)
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
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 scheduledkokeb_org.py --checkfinds 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 scheduledkokeb_org.py --checkfinds 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