ADR-0011: Repository root layout¶
- Status: Accepted
- Date: 2026-11-03
Context¶
A driver template whose root held about twenty entries (Doxyfile, mkdocs.yml, Kconfig, idf_component.yml,
.clang-format and .clang-tidy as symlinks into _config/, CONTRIBUTING.md, SECURITY.md and TEMPLATE.md
next to the README) did not let a reader see at a glance what a repository is, and the symlinks hid where the real
configuration lived: two names for one file, broken on Windows checkouts, and easy to edit in the wrong place. Tool
configuration was split between the root and _config/ with no rule for which went where.
ESP-IDF support was a wrapper component under examples/esp32/components/ that sourced the root Kconfig and the
build settings, plus a root idf_component.yml that no release used: the component manager does not need a
manifest for a git dependency, and the stack does not publish to the ESP Component Registry. The layout also read
as if the drivers were ESP32 drivers, though their code is MCU-agnostic and ESP32 is only the first example
platform.
Decision¶
- The root holds only (a) files GitHub or a tool requires at the root, and (b) the files a reader looks for first. For a driver or standalone library repository that is:
- Files:
README.md,LICENSE,CHANGELOG.md,CMakeLists.txt,AGENTS.md,CLAUDE.md,.gitignore,.gitmodules, anddriver.ymlin a driver (its metadata, read by kb-core's catalog). - Folders:
.github/,.claude/,_config/,cmake/,docs/,examples/,inc/,src/,tests/,tools/.
Other kinds keep their own source folders (kb-core: utils/, rtos/, interfaces/, handlers/, drivers/,
catalog/; kb-hal-common: include/, lib/, templates/) and add only what a tool requires at the root,
named in their AGENTS.md (for example CMakePresets.json, which CMake reads only from the source root).
2. One location for tool configuration: _config/. clang-format, clang-tidy, Doxyfile, mkdocs.yml
(docs_dir: ../docs), Kconfig, markdownlint, yamllint and lychee live there. Every command and workflow names
the path (--style=file:_config/.clang-format, --config-file=_config/.clang-tidy,
mkdocs build -f _config/mkdocs.yml, mkdocs_config / doxygen_config in the docs workflow). Doxygen runs
from the root, so paths inside _config/Doxyfile stay relative to the root.
3. No symlinks. Editors that find .clang-format / .clang-tidy only by name use a local copy that
.gitignore lists; nothing at the root is a link.
4. CONTRIBUTING.md and SECURITY.md live in .github/, where GitHub reads them as well.
5. One root CMakeLists.txt serves every build. Under ESP_PLATFORM it is the ESP-IDF component
(idf_component_register() from cmake/<chip>_build_settings.cmake, KCONFIG _config/Kconfig); otherwise it
is the CMake library with the <chip>::<chip> alias and install/export. An ESP-IDF project uses the repository
directly: EXTRA_COMPONENT_DIRS, a checkout under components/, or a component-manager git dependency. There
is no root idf_component.yml and no example wrapper component. A manifest is added only if registry
publishing is chosen. This ESP_PLATFORM branch is build glue; source files never test ESP_PLATFORM
(ADR-0014).
6. Drivers and libraries are MCU-agnostic. Platform code lives only in examples/<platform>/, one
self-contained folder per platform carrying its own port, built by CI. Every repository ships examples/host/,
which runs on any PC and is built and run in the host tests. Plain CMake covers STM32, RP2040, nRF and host
builds; Zephyr, Arduino or PlatformIO manifests are added only when a user needs them, without a second copy
of the sources. kb-core's interfaces/mcu/<family>/ and board HALs, which are MCU-specific by design through
their binds, are the documented exceptions.
Consequences¶
- A reader sees the README, the licence, the changelog and the build entry point, and every configuration is in one obvious place. The template's setup self-test fails when a generated root holds anything else.
- Tools are called with a path. The lint workflow takes
clang_format_config/clang_tidy_config; the docs tooling (kokeb-docs) takes the folder that holdsdocs_diras the repository root, finds_config/mkdocs.ymlon its own and acceptskokeb-docs -f. - ESP-IDF names a component after its folder, so a project that uses
EXTRA_COMPONENT_DIRSon a checkout requires the checkout folder's name; a submodule undercomponents/<chip>or a component-manager key gives a stable name. - Room for more platforms without touching the root: a new
examples/<platform>/with its CI job, and a manifest only when a build system cannot use the rootCMakeLists.txt.