jcoffey-dev
f1aff4ba07
GitHub took the organization's repos and GHCR offline on 2026-09-20. Repo, release, raw-file and clone links now go to Gitea at git.coffeylabs.org, container images to registry.coffeylabs.org, and GitLab-style /-/blob paths to Gitea's /src/branch form. Go module paths are identifiers and stay as they are; links to GitHub issues and pull requests are left as history.
2.7 KiB
Contributing to stalwart-migrator
How to build and test the tool, and where its design is written down. For what the tool does and how to use it, see the README.
Build and test
go build ./...
go test ./...
Requires Go 1.26.8 or newer. The tool is Go standard library only — no external dependencies — and nothing third-party is vendored.
To try a command from a checkout without installing it:
sudo go run ./cmd/stalwart-migrate preflight
docs/rehearsal.md explains why even read-only commands need write access to the checkpoint directory.
Releases
Releases are tagged by date, like ihasmail's: v2026.9.15, with .1, .2
added for another release the same day. Binaries for linux/amd64 and
linux/arm64 and a SHA256SUMS file are attached to every
release.
Every release is built by the release workflow
from a tagged commit on main, after the tests and a known-vulnerabilities
check pass. The archives are reproducible: scripts/build-release.sh builds the
same bytes from the same commit, so a release can be checked before tagging:
scripts/build-release.sh v2026.9.15 dist
If a pushed tag's run never starts, run the workflow by hand from the Actions tab and give it the tag.
Why not a shell script
Stalwart's 0.15 → 0.16 boundary is not a drop-in binary swap: settings move, and the data directory has to be migrated rather than merely copied. The failure mode that matters is a half-migrated mail store with no way back — which is why backup verification and checkpointing are the design center rather than conveniences bolted on afterwards — and why the tool refuses to cut over until you confirm you have a way back.
Where the design is written down
ARCHITECTURE.md covers the design in full: §1 on why a
thin wrapper is insufficient, §4 on the migration phases, §5 on the checkpoint
state machine, §6 on the CLI surface, and §8 on what is still open. It was
written before the implementation and records the reasoning; where it and the
code disagree about current behavior — the flags shown in §6, for example —
the code and stalwart-migrate <command> -h are right.
docs/status.md has the state of each command and package, and what has been tested against real servers.
Testing against something real
Where a phase runs an external program, its tests drive a fake one. That is sound for logic and ordering, and it is not evidence about production. Before trusting a change to a migration path, run it on a clone of a real server — see Rehearse on a clone first.