# B4L product repository template Every B4L product repository has the same layout, so people and proplan find the product image, the boards, the firmware and the libraries in the same place. This file explains the layout, the rules and `proplan.toml`. It is copied into every repository created from the template; keep it as the reference. ## Create a product repository In Gitea: **New Repository**, choose the template **B4L/product-template**, tick **Git Content**, give the repository the product's name and a description. Gitea puts the name into `README.md`, `CHANGELOG.md`, `proplan.toml` and the board folder under `hardware/` (the files listed in `.gitea/template`). Then: 1. Replace `assets/product.png` with a photo or render of the product (PNG, JPEG or WebP, at most 5 MB). 2. Create the KiCad project in the board folder (KiCad: File, New Project; the project file is `hardware//.kicad_pro`). 3. Commit and push. The KiBot workflow checks the board on every push. 4. Tag the first prototype `v0.1` when its boards are ordered, and link the tag to the stage on the project's Prototypes tab in proplan. ## Layout | Path | What goes there | |---|---| | `proplan.toml` | the manifest proplan reads (below) | | `README.md`, `CHANGELOG.md` | what the product is; one changelog section per stage (`## v0.2`) | | `assets/product.png` | the product image | | `hardware//` | one KiCad project per board | | `hardware/lib/` | symbols, footprints and 3D models shared by the boards | | `firmware//` | MCU code (STM32CubeIDE or CMake), `firmware/lib/` for shared drivers | | `external/` | third-party code as git submodules (e.g. ST's USB-PD middleware) | | `software//` | host tools and apps | | `mech/` | FreeCAD sources and STEP exports | | `sim/` | LTspice/ngspice, calculation scripts and notebooks | | `test//` | bench results per stage (`test/v0.1/`) | | `docs/`, `docs/datasheets/`, `docs/tex/` | documentation, vendor PDFs, LaTeX sources | | `.gitea/workflows/` | KiBot, release outputs, fabrication document | ## Rules - A board revision is a tag (`v0.1`, `v0.2`), never a copied folder (`kicad_v1_5/` next to `kicad_v1_6/`). A real variant built side by side (48 V and 24 V, 2-board and 3-board) is its own folder under `hardware/` and its own `[[boards]]` entry. - Generated output (gerbers, BOMs, production zips, PDFs, plots) is built by CI and attached to the release; it is not committed. - Vendor datasheets go to `docs/datasheets/`, not the repository root. - Third-party code is a git submodule in `external/` and is not edited here. - IDE build output and tool caches (`Debug/`, `__pycache__/`, `.claude/`, KiCad backups) stay out; `.gitignore` covers them. ## Versioning One repository, three kinds of tags. The prefix of a firmware or software tag is the folder it versions, so every target and every tool has its own releases, and the board release workflow (`v*`) never reacts to them. | What | Tag | Example | Scheme | |---|---|---|---| | Prototype stage (the whole product) | `vMAJOR.MINOR` | `v0.1`, `v0.2` | the next stage takes the next number; the tag proplan links to a stage and CI attaches the board outputs to | | Firmware target `firmware//` | `firmware//vMAJOR.MINOR.PATCH` | `firmware/main-mcu/v1.2.0`, `firmware/main-mcu/v1.3.0-rc.1` | SemVer 2.0 (semver.org) | | Software tool `software//` | `software//YYYY.MM.MICRO` | `software/diag/2026.10.0`, `software/diag/2026.10.1` | CalVer (calver.org) | Firmware (SemVer): - MAJOR when something outside the firmware has to change with it: CAN IDs or message layout, the protocol the host tools speak, the format of settings stored in flash, the bootloader interface. MINOR for new features that keep all of that, PATCH for fixes. - `0.y.z` while prototyping (anything may change), `1.0.0` with the first production firmware. Bench builds before a release are pre-releases (`v1.3.0-rc.1`, `-rc.2`). - The version is also where the build reads it (CMake `project( VERSION 1.2.0)` or a `version.h`), and the firmware reports it at run time (CAN, USB or UART), so a board on the bench says what it runs. Software (CalVer `YYYY.MM.MICRO`): - Year, month without a leading zero (calver.org's `MM`), and MICRO counting the releases of that month from 0: `2026.10.0`, `2026.10.1`, `2026.11.0`. Without the zero the number is also a valid version for pip (`pyproject.toml`) and Cargo. - A date, not a compatibility promise: a tool's README says which firmware MAJOR versions it talks to. For all three: - The tag is the source of truth. A version written in a file (`pyproject.toml`, `Cargo.toml`, CMake, `version.h`) matches the tag and changes in the commit that gets tagged. - A tag is never moved or reused; a bad release gets the next version. proplan flags a moved tag on its stage card. - Each firmware target and each tool keeps its own `CHANGELOG.md` in its folder. The root `CHANGELOG.md` has one section per prototype stage and lists the firmware and software versions that stage was built with. - Firmware and software releases are made by hand in Gitea for now (push the tag, then New Release); `release.yml` builds board outputs for `v*` tags only. ## proplan.toml proplan reads this file and the image it names, nothing else of the repository's content: at the default branch for the Code tab, and at a stage's tagged commit for the stage's card (so the card shows the product as it was at that tag). Every key is optional. ```toml schema = 1 # 1; a newer schema is refused [product] name = "papir" # default: the repository's name image = "assets/product.png" # PNG, JPEG or WebP, at most 5 MB; none when left out [[boards]] # one per KiCad project, as many as needed name = "papir" # default: the folder's last part path = "hardware/papir" # required [paths] # each default: the folder of the same name firmware = "firmware" software = "software" mech = "mech" sim = "sim" test = "test" docs = "docs" external = "external" ``` Paths are relative to the repository root (no leading `/`, no `..`). A board, a path written under `[paths]` or the image that does not exist is reported on the Code tab ("proplan.toml: missing ..."); a path left out that does not exist is simply not shown. Unknown keys are ignored. ## Adopting the layout in an existing repository An existing repository does not have to move anything: a `proplan.toml` that names the current folders is enough, and history and open work stay as they are. Moving folders to the template's names can follow later. papir (KiCad project in `papir/`, firmware in `code/`): ```toml [[boards]] name = "papir" path = "papir" [paths] firmware = "code" software = "pirnet" mech = "mech" docs = "docs" ``` LVSolarBuck (the current board in `kicad48V-R/LVSolarBuck`, firmware in `code64/`): ```toml [product] image = "housing.png" [[boards]] name = "LVSolarBuck" path = "kicad48V-R/LVSolarBuck" [paths] firmware = "code64" sim = "ltspice" test = "testing" docs = "docs" ``` PowerModule (three board variants): ```toml [product] image = "images/render-display.png" [[boards]] name = "PowerModule" path = "kicad/PowerModule" [[boards]] name = "PowerModule48" path = "kicad/PowerModule48" [[boards]] name = "PowerModule48PD" path = "kicad/PowerModule48PD" [paths] firmware = "code" software = "tools" sim = "ltspice" test = "testing" docs = "tex" external = "external" ``` ## CI - `.gitea/workflows/kibot.yml`: on a push that touches `hardware/`, KiBot runs ERC and DRC and builds schematic PDF, gerbers, drill files, pick and place and BOM for every board (`hardware/*/*.kicad_pro`); the outputs are kept as a workflow artifact. - `.gitea/workflows/release.yml`: on a tag `v*`, the same outputs are zipped per board and attached to the tag's release (created when missing). The Actions token must be allowed to write releases. Firmware and software tags (`firmware/...`, `software/...`) do not start it. - `.gitea/workflows/docgen.yml`: with a `docs/input.md` (typecad-docgen front matter, as in PowerModule), builds the fabrication document of the first board and pushes it to the `docu` branch. All three use the runner label `kicad10_auto` (as LVSolarBuck). They were adapted from LVSolarBuck and PowerModule and run for the first time when the first board is committed and tagged; check that first run.