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.

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.