Releasing

Release conventions for Wakeplane. This page covers versioning policy, artifact expectations, docs verification, and what constitutes a breaking change.

Versioning

Wakeplane follows Semantic Versioning:

MAJOR - breaking changes to API contract, CLI interface, or storage schema
MINOR - new features, new endpoints, new policy types, backwards-compatible schema migrations
PATCH - bug fixes, test improvements, documentation updates

The 1.x release line follows the Stable Contract. Historical 0.x releases were pre-stable. Stable compatibility applies to documented interfaces and supported deployment boundaries.

Version source

Version is defined as a constant in both entry points:

cmd/wakeplane/main.go - const version = "1.0.0"
cmd/wakeplaned/main.go - const version = "1.0.0"

Both must be updated in lockstep before tagging. The version is surfaced in:

GET /v1/status -> version field
Embedded applications pass their own version string to config.FromEnv

Release checklist

Before tagging a release:

All tests pass: go test -race ./... -count=1
Build succeeds: go build ./...
SMALL strict check passes: small check --strict
Generated docs are current: go run ./tools/docsgen --check
Public docs validation passes: docs tests reject unsupported fields, fantasy commands, and unknown API paths
Version constants updated in both cmd/wakeplane/main.go and cmd/wakeplaned/main.go
Install and release notes updated under docs/public/
Hosted installer default version updated if wakeplane.dev/install.sh should point at this release
No uncommitted changes: git status is clean

Release artifacts

Tagged releases must publish:

wakeplane_<version>_darwin_arm64.tar.gz
wakeplane_<version>_linux_amd64.tar.gz
wakeplane_<version>_linux_arm64.tar.gz
checksums.txt

Each archive includes wakeplane, wakeplaned, and the separate automation-runner. The hosted installer installs the CLI and daemon.

The release workflow builds artifacts with scripts/build-release-artifacts.sh and attaches them to the GitHub release for tagged versions.

Release notes

Each release page should include:

version
date
what changed
breaking changes
upgrade notes
known limitations

Current release notes:

What constitutes a breaking change

The following require a MAJOR version bump after 1.0.0 (or a clear release note during 0.x):

Removing or renaming an HTTP API endpoint
Changing the error envelope shape (fields, codes, HTTP status mapping)
Changing run status values or transition semantics
Changing the schedule YAML manifest schema (required fields, field names, value semantics)
Changing the storage schema in a non-migratable way
Changing CLI command names or required flags
Removing a policy type or changing its default behavior
Removing a supported executor kind

Adding new optional fields, new endpoints, new policy types, or new executor kinds is not a breaking change.

Two binaries: `wakeplane` and `wakeplaned`

Both binaries share the same command surface and configuration in the v1.0.0 source line.

wakeplaned follows Unix daemon naming conventions (sshd, httpd) for process listing, packaging disambiguation, and future deployment tooling. The split into two entry points is intentional and forward-looking - they may diverge if the daemon gains additional OS-level integration (systemd notify, privilege dropping, PID file management).

Do not treat wakeplaned as deprecated. Both binaries are maintained.