Versioning and releases
Two things carry a version, and they are kept apart on purpose.
The app
The number lives in soldermask/version.py (__version__), follows semantic versioning, and must agree with a section in CHANGELOG.md and a git tag. soldermask release keeps the three in step so they cannot drift:
soldermask release note "Added a diff between versions" --kind Added # as you go
soldermask release show # what is waiting
soldermask release bump minor # 0.1.0 -> 0.2.0bump rewrites version.py, moves everything under Unreleased into a dated ## 0.2.0 — 2026-09-02 section, commits the two files and tags v0.2.0. It refuses to release with nothing under Unreleased unless --allow-empty; --no-git edits the files only; --dry-run shows what would happen.
soldermask version prints what is running, including the commit and whether the tree is dirty: soldermask 0.1.0+g46ae848.dirty (project format 2). /about and /api/app show the same.
Where it stands
No release has been cut since 0.1.0 (1 Sep 2026, tag v0.1.0, the only tag). Everything since sits under Unreleased in CHANGELOG.md, and Unreleased is also the research log: 600 entries on 16 Nov 2026, 445 of them opening on a bolded claim, experiments and nulls beside features and fixes. So:
version.pystill says0.1.0, and every version a project has saved records app version0.1.0(projects.pywrites__version__, not the commit). Onlysoldermask versionnames the commit that is running.soldermask release bumpwould move the whole research log into the new release's section. Cutting the next release means deciding first what of Unreleased is release notes and what stays as the log.- The table below is the rule a release would follow; between 1 Sep and today features, endpoints and flags have landed without a bump.
The project format
FORMAT in version.py is the on-disk layout number of a project directory. It changes only when project.json or the version folders change shape, and it changes rarely. Every project records the format it was written in; the app migrates older ones on read (keeping a backup) and refuses newer ones. Bump it, add a migration step in soldermask/projects.py, and describe the change in Projects on disk.
Each project's versions
v001, v002, … under projects/<slug>/ — immutable directories, one per build, each recording the app version that made it. See Versions and history.
What goes where
| Change | Bump | Also |
|---|---|---|
| a fix, no format change | patch | changelog note |
| a feature, an endpoint, a flag | minor | changelog note, docs page |
a change to project.json or the version directory | minor or major | FORMAT + migration + docs |
| removing a command, endpoint or field | major | changelog under Removed |