From 0e002be80cf7c55adb5b7259c9c1c9f3660bbf88 Mon Sep 17 00:00:00 2001 From: grabowski Date: Tue, 13 Oct 2026 16:56:22 +0700 Subject: [PATCH] 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 | 5 ++++- README.md | 10 +++++++++ TEMPLATE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++- firmware/README.md | 5 +++++ software/README.md | 5 +++++ 5 files changed, 74 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cef4f91..13d1a2e 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/README.md b/README.md index c5b40d9..5d26bfa 100644 --- a/README.md +++ b/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//v1.2.0` | SemVer | +| Software tool | `software//2026.10.0` | CalVer `YYYY.MM.MICRO` | + +TEMPLATE.md has the rules (what counts as breaking, pre-releases, changelogs). diff --git a/TEMPLATE.md b/TEMPLATE.md index 86dc5e8..6901eb9 100644 --- a/TEMPLATE.md +++ b/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//` | `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 @@ -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. diff --git a/firmware/README.md b/firmware/README.md index ac3e798..c1dfec0 100644 --- a/firmware/README.md +++ b/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//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. diff --git a/software/README.md b/software/README.md index 8a71fb4..7227368 100644 --- a/software/README.md +++ b/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//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.