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)

Release artifacts

Artifact

Current status

Source repository

The primary artifact. go build ./cmd/karkain produces the toolchain; all documentation and examples are in the repository.

GitHub Releases (binaries)

Available — the v1.2.0 archives (13-target matrix) are published to GitHub Releases with checksums.txt (SHA-256). They were built locally on a Windows host from the tagged commit with Go 1.21.13 (the Go version the CI workflow pins) and packaged with the local Windows tools — NOT by the tag-triggered CI pipeline, which did not complete because the account was subject to a billing/payment restriction (run 43374786565). This is a locally built and published release, NOT a CI-green release.

Source archives

GitHub auto-generates source tarballs/zip for every tag once tags are cut.

Documentation

Sphinx-built and published from docs/source (deployed to GitHub Pages by .github/workflows/docs.yml).

Checksums

SHA-256 computed over every release archive at publish time (for v1.2.0, computed locally from the artifacts themselves and independently verified, sha256sum -c-compatible).

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.

Release build identity

Property

Value / requirement

Go version requirement

Go 1.21+ (CI uses actions/setup-go with 1.21; verified with Go 1.27 locally).

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

go build -o karkain ./cmd/karkain (CI strips with -ldflags="-s -w" for release archives). CGO_ENABLED=0 for cross builds.

Version injection

None required: the version is a compiled constant (Karkain Compiler v1.2.0, VERSION = 1.2.0).

Output artifact

A single platform binary named karkain / karkain.exe.

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 build/run transpile to C before compiling natively.

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.ps1 workflow verifies an installed binary against the current source tree before the smoke test.

Hygiene

  • Generated release artifacts live under releases/, dist/, .build/ and artifacts/ — 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.