Skip to content

Version releases with SemVer 0.x and a hand-written changelog - #70

Merged
chrislaupama merged 2 commits into
mainfrom
versioning-changelog
Nov 14, 2026
Merged

chrislaupama merged 2 commits into
mainfrom
versioning-changelog

Conversation

@chrislaupama

Copy link
Copy Markdown
Collaborator

Closes #37.

Decisions

  • Scheme: SemVer, on 0.x while Device is pre-alpha.
    • A minor bump is for new features or changes that break older projects.
    • A patch bump is for fixes only.
    • The project file format keeps its own version.
  • Pre-releases: tagged vX.Y.Z-alpha.N, -beta.N or -rc.N, and published as GitHub pre-releases.
  • Changelog: a hand-written CHANGELOG.md in Keep a Changelog style. Release notes are the version's changelog section, followed by GitHub's generated list of pull requests. PROGRESS.md stays the development log.
  • Who bumps: a release PR bumps Cargo.toml and moves the Unreleased entries under the new version. After it merges, the tag goes on that commit.

Changes

  • CHANGELOG.md (new): explains the scheme and has an Unreleased section summarising what 0.1.0 will contain.
  • .github/workflows/release.yml, version job: a release tag now also has to be X.Y.Z or a pre-release of it, and must have a changelog section. Both are checked before anything builds.
  • .github/workflows/release.yml, release job: it sparse-checks-out the changelog and uses the section as --notes-file together with --generate-notes. A version with a - gets --prerelease.
  • tools/release/changelog-notes.sh (new): extracts the section and fails on a missing or empty one.
  • tools/release/test-changelog-notes.sh (new): five small cases, now run by lint:
    • a dated section
    • a pre-release with subheadings
    • a missing version
    • an empty section
    • a version that is a prefix of another
  • Docs: docs/building.md gets a new "Versions and releases" section with the steps. CONTRIBUTING asks for a changelog line with user-visible changes, and the README status row mentions macOS signing.

Testing

Run locally:

$ bash tools/release/test-changelog-notes.sh
changelog-notes: all checks passed
$ shellcheck -S warning tools/release/changelog-notes.sh tools/release/test-changelog-notes.sh
(clean)

The release job itself only runs on a pushed v* tag, so the first real run is the first release.

No screenshots, because nothing in the app changes. No benchmarks, because no runtime code changes.


Generated by Claude Code

Releases use Semantic Versioning, 0.x while pre-alpha (a minor bump for
features or project-breaking changes, a patch bump for fixes), with
-alpha.N, -beta.N and -rc.N pre-releases. CHANGELOG.md (Keep a Changelog)
is the user-facing list of changes; PROGRESS.md stays the development log.

The Release workflow now rejects a tag whose version isn't X.Y.Z or a
pre-release of it, or that has no CHANGELOG.md section. The draft release
uses that section as its notes, followed by GitHub's generated list of pull
requests, and marks pre-release versions as GitHub pre-releases. The
section is extracted by tools/release/changelog-notes.sh, which lint now
tests.

docs/building.md describes the scheme and the release steps; CONTRIBUTING
asks for a changelog line with user-visible changes.

Closes #37
@chrislaupama
chrislaupama marked this pull request as ready for review November 14, 2026 23:06
@chrislaupama
chrislaupama merged commit 3b05023 into main Nov 14, 2026
24 checks passed
@chrislaupama
chrislaupama deleted the versioning-changelog branch November 14, 2026 23:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Choose a versioning scheme and changelog for releases

1 participant