Skip to content
dockmesh

Release Process

The nuts-and-bolts of how releases happen. Useful if you’re contributing, tracking specific commits, or planning upgrades.

Versioning

Section titled “Versioning”

Semantic Versioning strictly:

  • MAJOR.MINOR.PATCH
  • Pre-release suffixes: -alpha.N, -beta.N, -rc.N
  • Example: 1.2.3, 1.3.0-beta.2, 2.0.0-rc.1

What each level means in practice:

LevelContains
Patch (1.2.3 → 1.2.4)Bug fixes, security patches, no new features
Minor (1.2 → 1.3)New features, deprecations, no breaking changes
Major (1 → 2)Breaking changes, removed deprecated features

Branches

Section titled “Branches”
  • main — always shippable. Every merge passes CI.
  • feat/*, fix/* — feature / fix branches, merged into main via PR.

Long-lived release branches (release/1.x style) are not in use today — dockmesh is pre-1.0 and the active line is whatever’s on main. If a parallel maintenance line becomes necessary post-1.0, the convention will be added then.

Release cycle

Section titled “Release cycle”

dockmesh is pre-1.0 — there’s no strict 4-week cadence yet. Releases are cut when there’s enough accumulated work and a stable point on main. Patch releases ship on demand when a bug or security issue warrants a quick fix.

When the project goes 1.0 and a published cadence makes sense, it will be documented here. Until then, watch the GitHub releases for actual ship dates and the changelog for what’s in each.

Release artifacts

Section titled “Release artifacts”

Every tagged release produces these tarballs on the GitHub Release page. Each tarball bundles dockmesh (server), dockmesh-agent, and dmctl together — one download covers everything:

ArtifactWhere
dockmesh_linux_amd64.tar.gzGitHub Release
dockmesh_linux_arm64.tar.gzGitHub Release
dockmesh_darwin_amd64.tar.gzGitHub Release
dockmesh_darwin_arm64.tar.gzGitHub Release
checksums.txtGitHub Release — BSD-style SHA-256 lines, verify with sha256sum -c or shasum -a 256 -c
Release notesGitHub Release page

Not shipped yet (roadmap):

  • linux/arm/v7 builds (Raspberry Pi 2 / 3 32-bit, Banana Pi)
  • Native Windows binaries (no Server / Agent / dmctl for Windows; use WSL)
  • Published Docker image at ghcr.io/dockmesh/dockmesh — a Dockerfile ships in the repo, but the pipeline doesn’t push the image yet
  • GPG-signed checksums

Builds are reproducibility-friendly (-trimpath, -ldflags="-s -w") but the pipeline doesn’t run a full reproducible-build verification step today.

Build pipeline

Section titled “Build pipeline”

Releases are cut via GitHub Actions, triggered by pushing a v*.*.* tag:

  1. Maintainer tags the commit: git tag v0.2.x && git push --tags
  2. GitHub Actions triggers .github/workflows/release.yml:
    • Build the frontend (npm ci && npm run build) and copy web/build/* into cmd/dockmesh/web_dist/ for go:embed
    • Cross-compile the Go binaries for the four target platforms with embedded version / commit / build-date via -ldflags
    • Pack each platform’s dockmesh + dockmesh-agent + dmctl into a .tar.gz
    • Compute SHA-256 checksums for every tarball into checksums.txt
    • Create / update the GitHub Release and attach all tarballs + checksums.txt

Lint, unit tests, and end-to-end tests run as part of normal PR CI before the merge that lands the release commit — not inside the release pipeline itself. If the release tag points at a commit that didn’t pass PR CI, that’s on the maintainer; the release job won’t independently re-verify.

Verifying a release

Section titled “Verifying a release”

Every release attaches a checksums.txt next to the tarballs. To verify a download:

Terminal window
TAG=v0.2.x   # the release you downloaded
curl -fsSL https://github.com/Dockmesh/dockmesh/releases/download/${TAG}/checksums.txt -o checksums.txt
sha256sum -c checksums.txt   # or `shasum -a 256 -c` on macOS

GPG-signed checksums (checksums.txt.asc) are not produced today. Hardware-key-backed signing is a planned improvement. The recommended install path is the one-line installer (curl … | sudo bash), which already performs the SHA-256 check automatically before installing.

Emergency security releases

Section titled “Emergency security releases”

Out-of-band for critical vulnerabilities:

  1. Fix developed privately on a security branch
  2. CVE reserved if applicable
  3. Fix released as a patch to all supported versions
  4. Advisory published simultaneously to GitHub Security Advisories + security@dockmesh.dev subscribers

No public discussion of the vulnerability until release is published.

Supported versions

Section titled “Supported versions”

Only the most recent minor version receives all updates. Older minor versions get critical security fixes for 6 months after the next minor release.

Example: when 1.3.0 ships, 1.2.x gets security fixes for 6 months, then is EOL’d.

Check SECURITY.md for current supported versions.

How to stay current

Section titled “How to stay current”
  • Watch GitHub releases — get notifications per release
  • Follow the Changelog RSS — curated, less noise than raw releases
  • Subscribe to security advisories — GitHub repo → Settings → Notifications → Security alerts

Downgrade policy

Section titled “Downgrade policy”

Downgrades are not officially supported across database migrations. The server refuses to start if the DB schema is newer than the binary expects.

If you absolutely must downgrade (e.g. a regression you can’t work around):

  1. Stop the server
  2. Restore a pre-upgrade backup
  3. Install the old binary
  4. Start

This loses any data changes made after the upgrade.

See also

Section titled “See also”