Versioning and Release Tarball — Design

Date: 2026-05-05
Status: Approved (brainstorm complete); implementation plan to follow
Scope: Establish a single canonical version for the zyginit suite (zyginit + zygctl + sysv-wrapper), wire --version flags into all three binaries, and add scripts to bump the version and produce a source release tarball for vendoring into Hammerhead.

1. Goal

Hammerhead consumes zyginit as a vendored source drop into hammerhead-userland (per docs/SMF_MIGRATION.md). To make that drop reproducible and auditable, zyginit needs:

1. A single canonical version, tracked in source.
2. A scripted bump that updates every place the version appears, in lock-step.
3. A scripted release that produces releases/zyginit-<version>-source.tar.xz plus a .sha256 companion.
4. A runtime --version flag on every shipped binary, so an installed Hammerhead system can answer "which zyginit am I running?".

This work intentionally mirrors Coral's scripts/make-release.sh pattern (single tarball, sha256, --transform-prefixed paths) — the Hammerhead team gets a consistent shape across Zygaena projects.

2. Non-goals

• No CI/CD release automation. Bump and release are run by hand by a maintainer; no GitHub/Hg-server hooks, no signing, no upload step.
• No reproducible-build flags (--mtime, --owner=0, --sort=name). Coral doesn't bother and Hammerhead's packaging step is what produces the OS-level reproducible artifact. Adding these is a trivial follow-up if needed.
• No multi-tarball releases. The whole suite (zyginit + zygctl + sysv-wrapper) ships and versions together, in one tarball.
• No CHANGELOG.md integration. The bump script doesn't touch a changelog. (We can add this later; there is no changelog file today to integrate with.)
• No GPG signing. Hammerhead handles signing at the OS package layer.

3. Versioning policy

Semver: MAJOR.MINOR.PATCH.

While zyginit is pre-1.0, breaking changes may land in MINOR per semver convention. Once 1.0 ships (target: when SMF removal from Hammerhead is complete and the suite has been running unmodified for one release cycle), strict semver applies.

4. Source of truth

The root reef.toml [package].version is canonical. Every other location is derived and regenerated by the bump script.

Today's drift inventory (rev 82, version 0.1.0) — the bump script must keep these all consistent:

Generated files (version.reef × 2 and version.h) are committed to the repository so a tarball recipient can build without rerunning the bump script. They carry a "Generated by scripts/bump-version.sh — do not edit by hand" comment.

5. scripts/bump-version.sh

Usage: scripts/bump-version.sh <new-version>

Behavior:

1. Validates <new-version> matches ^[0-9]+\.[0-9]+\.[0-9]+$. Refuses if not.
2. Reads current version from root reef.toml. Refuses if <new-version> equals current.
3. Rewrites all five locations listed in §4.
4. Prints a summary diff (hg diff --stat) and a suggested commit command:

   $ hg ci -m 'Bump version to <new-version>'
   

5. Does not auto-commit. The maintainer reviews and commits by hand.

Generated file templates:

src/version.reef (and identical-content tools/zygctl/src/version.reef):

/* SRCHEADER... */

module version

// Generated by scripts/bump-version.sh — do not edit by hand.
pub fn VERSION(): string
    return "0.1.0"
end VERSION

end module

tools/sysv-wrapper/version.h:

/* SRCHEADER... */
/* Generated by scripts/bump-version.sh — do not edit by hand. */
#ifndef ZYGINIT_VERSION_H
#define ZYGINIT_VERSION_H
#define ZYGINIT_VERSION "0.1.0"
#endif

Both templates use the project's standard SRCHEADER.txt header. The bump script fills in ${project} from each subproject's own reef.toml [package].name (i.e., zyginit for src/version.reef, zygctl for tools/zygctl/src/version.reef), ${file.name} from the filename, and ${file.description} with a fixed string ("Generated version constant").

6. scripts/make-release.sh

Usage: scripts/make-release.sh [version-override]

Behavior (mirrors Coral's make-release.sh):

1. Reads version from root reef.toml, or uses [version-override] if provided.
2. Creates releases/ if missing.
3. Produces releases/zyginit-<version>-source.tar.xz via tar --transform "s,^,zyginit-<version>-source/," -cJf ....
4. Generates releases/zyginit-<version>-source.tar.xz.sha256.
5. Prints final paths and the sha256.

Tarball contents (top-level paths, --transform-prefixed into zyginit-<version>-source/):

Tarball excludes:

tar's --exclude patterns are passed in for each item. The exclusion of tools/*/build/ is critical — the global build/ exclude only covers the repo-root build dir.

7. Code changes (one-time)

These ride along with the introduction of the bump/release scripts:

The argv[0]-basename trick in sysv-wrapper means halt --version prints halt 0.1.0, reboot --version prints reboot 0.1.0, etc. — consistent with how each personality identifies itself in normal output.

8. Output format

A single line, <binary> <version>, exit 0. Matches Coral and the GNU/BSD common case:

$ zyginit --version
zyginit 0.1.0
$ zygctl --version
zygctl 0.1.0
$ halt --version
halt 0.1.0

zygctl version (no dashes — already a subcommand) continues to work and prints the same line. Both zygctl --version and zygctl version are strictly local — they print zygctl's compiled-in version and never round-trip the socket. This is the standard Unix convention and keeps the answer trustworthy when the daemon is wedged.

Querying the running daemon's version (useful during a partial upgrade) is an existing socket command (socket.reef:247) but is currently unreachable from zygctl. Wiring up a separate zygctl daemon-version subcommand to surface it is out of scope for this design — see §10.

9. End-to-end workflow

Maintainer cuts release 0.2.0:

$ scripts/bump-version.sh 0.2.0
zyginit: bumping 0.1.0 -> 0.2.0
  rewriting reef.toml
  rewriting tools/zygctl/reef.toml
  regenerating src/version.reef
  regenerating tools/zygctl/src/version.reef
  regenerating tools/sysv-wrapper/version.h
done. review with `hg diff` and commit:
  hg ci -m 'Bump version to 0.2.0'

$ hg diff --stat
 reef.toml                          | 2 +-
 tools/zygctl/reef.toml             | 2 +-
 src/version.reef                   | 2 +-
 tools/zygctl/src/version.reef      | 2 +-
 tools/sysv-wrapper/version.h       | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

$ hg ci -m 'Bump version to 0.2.0'

$ scripts/make-release.sh
Creating release: zyginit-0.2.0-source
Created: releases/zyginit-0.2.0-source.tar.xz
-rw-r--r-- 1 ctusa ctusa 1234567 May  5 15:30 releases/zyginit-0.2.0-source.tar.xz
Checksum: releases/zyginit-0.2.0-source.tar.xz.sha256
abc123...  releases/zyginit-0.2.0-source.tar.xz

Hammerhead then consumes the tarball + sha256 into hammerhead-userland, per the integration steps in docs/SMF_MIGRATION.md.

10. Open questions / future work

• scripts/install-to-be.sh already exists. Out of scope for this design — it's an in-place dev install, not a release artifact path.
• Reproducible tarballs (--mtime, --sort=name, --owner=0, --group=0). Add when the Hammerhead build needs byte-identical tarballs across maintainer machines.
• CHANGELOG.md — add when there's enough release history to warrant one. The first one or two release notes can live in commit messages.
• GPG signing — Hammerhead handles this at the OS package layer; no zyginit-side signing planned.
• Pre-release versions (e.g., 0.2.0-rc1). Not supported by the regex in §5. Add when needed.
• zygctl daemon-version subcommand. The socket already exposes a version command (socket.reef:247) that returns the running daemon's version, but no client surfaces it. Add a zygctl daemon-version (or similar) subcommand to make partial-upgrade diagnosis easy. Until then, socket.reef's version handler stays as accessible-but-unused (an echo version | nc -U /var/run/zyginit.sock still works).