===================== 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. .. contents:: Sections :local: :depth: 1 Artifact model (what exists today) ================================== .. list-table:: Release artifacts :widths: 34 66 :header-rows: 1 * - 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) - :implemented:`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 :doc:`/getting-started/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. .. list-table:: Release build identity :widths: 30 70 :header-rows: 1 * - 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: .. code-block:: text 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. .. seealso:: :doc:`/status/rc-checklist` — the acceptance criteria tied to release engineering. :doc:`/status/compatibility` — what releases may contain during the freeze. :doc:`/getting-started/installation` — what external developers actually run today.