soldermaskdocs

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.0

bump 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.py still says 0.1.0, and every version a project has saved records app version 0.1.0 (projects.py writes __version__, not the commit). Only soldermask version names the commit that is running.
  • soldermask release bump would 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

ChangeBumpAlso
a fix, no format changepatchchangelog note
a feature, an endpoint, a flagminorchangelog note, docs page
a change to project.json or the version directoryminor or majorFORMAT + migration + docs
removing a command, endpoint or fieldmajorchangelog under Removed

On this page