Versioning: stages v0.1, firmware SemVer, software CalVer

TEMPLATE.md Versioning section; notes in README, CHANGELOG and the firmware/software READMEs. Source: contrib/product-template in B4L/proplan.

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog: $REPO_NAME
 
-One section per prototype stage, newest first; the heading is the tag.
+One section per prototype stage, newest first; the heading is the tag, and
+the section lists the firmware and software versions the stage was built
+with. Each firmware target and each tool keeps its own CHANGELOG.md in its
+folder.
 
 ## v0.1 (planned)
 

README.md

@@ -23,3 +23,13 @@ TEMPLATE.md explains the layout, the rules and `proplan.toml`.
 Each prototype is a git tag (`v0.1`, `v0.2`, ...). CI builds gerbers, BOM and
 schematic PDFs for the tag and attaches them to its release; CHANGELOG.md says
 what each stage changes. In proplan the prototype stage links the tag.
+
+## Versioning
+
+| What | Tag | Scheme |
+|---|---|---|
+| Prototype stage | `v0.1`, `v0.2` | the next stage takes the next number |
+| Firmware target | `firmware/<target>/v1.2.0` | SemVer |
+| Software tool | `software/<tool>/2026.10.0` | CalVer `YYYY.MM.MICRO` |
+
+TEMPLATE.md has the rules (what counts as breaking, pre-releases, changelogs).

TEMPLATE.md

@@ -53,6 +53,54 @@ description. Gitea puts the name into `README.md`, `CHANGELOG.md`,
 - 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/<target>/` | `firmware/<target>/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/<tool>/` | `software/<tool>/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(<name> 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
@@ -158,7 +206,8 @@ external = "external"
   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.
+  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.

firmware/README.md

@@ -5,3 +5,8 @@ example `firmware/main-mcu/`. Drivers shared by the targets go to
 `firmware/lib/`; third-party stacks (HAL, USB-PD middleware) are submodules in
 `external/`. IDE build folders (`Debug/`, `Release/`, `build/`) are not
 committed.
+
+Versions: SemVer per target, tagged `firmware/<target>/vMAJOR.MINOR.PATCH`
+(for example `firmware/main-mcu/v0.1.0`). Each target folder has its own
+`CHANGELOG.md`, and the firmware reports its version at run time. TEMPLATE.md
+says what counts as breaking and how pre-releases are named.

software/README.md

@@ -3,3 +3,8 @@
 Host tools and apps (diagnostics, configuration, test rigs), one folder per
 tool, for example `software/diag/` with its own README and pyproject.toml or
 Cargo.toml.
+
+Versions: CalVer per tool, tagged `software/<tool>/YYYY.MM.MICRO` (for
+example `software/diag/2026.10.0`: month without a leading zero, MICRO
+counting that month's releases from 0). Each tool folder has its own
+`CHANGELOG.md`, and its README says which firmware MAJOR versions it talks to.