Release Engineering
This page documents how Karkain releases are produced, how they can be reproduced, and what the artifact model is. Today the pre-built v1.2.0 archives are published on GitHub Releases (locally built and published — see below); building from source remains supported for every platform.
Artifact model (what exists today)
Artifact |
Current status |
|---|---|
Source repository |
The primary artifact. |
GitHub Releases (binaries) |
Available — the v1.2.0 archives (13-target matrix)
are published to GitHub Releases with
|
Source archives |
GitHub auto-generates source tarballs/zip for every tag once tags are cut. |
Documentation |
Sphinx-built and published from |
Checksums |
SHA-256 computed over every release archive at publish time (for
v1.2.0, computed locally from the artifacts themselves and
independently verified, |
The published v1.2.0 archives were built and packaged locally (see above); the Installation page describes how to install them and how to build from source. No page advertises a download that does not exist.
Reproducible release build
The toolchain is built from source with an unmodified checkout on the
release commit. Version identity is compiled in (a single constant in
cmd/karkain/main.go) and matches the VERSION file at the repository
root, so there are no hidden -ldflags version-injection hoops.
Property |
Value / requirement |
|---|---|
Go version requirement |
Go 1.21+ (CI uses |
OS |
Windows, Linux, macOS, FreeBSD build hosts (CI supports a 12-target matrix). |
Architecture |
amd64, arm64, armv7, i386, ppc64le, s390x (13-target release matrix). |
Build flags |
|
Version injection |
None required: the version is a compiled constant
( |
Output artifact |
A single platform binary named |
Checksum |
SHA-256 computed over each release archive at publish time. |
Runtime dependency |
A C compiler (GCC/Clang, or MSVC on Windows) is required on the
target machine because |
Checksums
Release archives carry SHA-256:
For v1.2.0, generated locally from the artifacts themselves and independently verified; embedded in the release assets as
checksums.txt.The local
scripts/verify-install.ps1workflow verifies an installed binary against the current source tree before the smoke test.
Hygiene
Generated release artifacts live under
releases/,dist/,.build/andartifacts/— every one is covered by.gitignore.*.exe,*.c,*.c23,docs/build/and temporary directories are ignored and must not be committed.Release scripts never force-push, never rewrite history, and never commit binaries.
Local release checklist
For a maintainer producing a local source release:
1. git checkout the tagged commit (clean tree).
2. karkain --version # matches the tag
3. go clean -cache # optional: clean build machine
4. go build -o karkain ./cmd/karkain # release binary
5. ./karkain --version
6. scripts/verify-install.ps1 # verify install + smoke
7. python -m sphinx -b html -W --keep-going docs/source docs/build/html
8. python -m sphinx -b linkcheck -W docs/source docs/build/linkcheck
CI (for a tagged GitHub release) does the same matrix build, packages the
archives with README.md, LICENSE and VERSION, computes SHA-256
checksums and publishes the GitHub Release. For v1.2.0 the CI pipeline did
not complete (the account was subject to a billing/payment restriction;
run 43374786565), so the published archives were produced locally with
the same Go version and build flags; see the artifact model above.
See also
Release-Candidate Checklist — the acceptance criteria tied to release engineering. Compatibility Policy — what releases may contain during the freeze. Installation — what external developers actually run today.