Skip to content

Release Management

Jump to bottom
yellowbean edited this page Oct 19, 2026 · 4 revisions

Release Management

Change Logs

  • New -> Noticeable cool stuff to users
  • ENHANCEMENT -> Invisible to user but makes something better
  • BREAK -> code change required from user
  • FIX -> no code change but result calculated changed

Versioning

Hastructure versions read MAJOR.MINOR.PATCH (e.g. 0.52.13). The Python client (absbox) gates on the MAJOR.MINOR pair only: a 0.52.x client works with any 0.52.x engine, so PATCH releases are always additive for users.

Two tracks are active, selected by the tag prefix:

Prefix Example Track What CI does
v v0.52.13 release workflow docker-image.yml ("Docker Image CI"): builds native binaries for linux/amd64, linux/arm64, macOS/arm64 and Windows/amd64, publishes a GitHub Release (non-draft, generated notes) and attaches the binaries, pushes the Docker Hub image as latest + 0.52.13 + v0.52.13, runs the Hackage publish in dry-run mode
a a0.52.13 dev workflow docker-image-dev-by-tag.yml ("Docker Image CI Dev A Tag"): builds multi-arch images natively (amd64 + arm64, no QEMU), smoke-tests the image against /version, pushes yellowbean/hastructure:dev + yellowbean/hastructure:a0.52.13. No GitHub Release is created.

A merged PR to the default branch also refreshes yellowbean/hastructure:dev (amd64 only, via docker-image-dev.yml).

l-prefixed LTS tags are described below for completeness but are not consumed by any workflow today.

Hastructure adopts similar strategy of Ubuntu, there are three version outstanding:

  • LTS -> which keeps backward compatible API with hotfix only, the support covers 3 year since first release. (tagged l*, not in use yet)
  • Stable -> may merge features from Dev, (tagged a* -> the dev docker track)
  • Dev -> actively being tested and including new features/APIs.

Note: an earlier version of this page mapped v to Dev and a to Stable — that was the reverse of what the workflows do. The mapping above matches .github/workflows/* as of Oct 2026.

How to publish

All commands run on the working branch (currently Sep26); release files are staged by just tag-files. Test first with just test (cabal test).

Dev engine image (the dev tag on Docker Hub)

just update-version 0.52.13     # rewrites version in Hastructure.cabal
# add the CHANGELOG.md entry under the towncrier marker
just tag-files a 0.52.13        # stages CHANGELOG.md, app/Main.hs, Hastructure.cabal, swagger.json;
                                # commits "bump version to-> < 0.52.13 >", creates annotated tag
                                # a0.52.13, pushes branch + tag

CI then builds and pushes yellowbean/hastructure:dev (multi-arch) — watch it under the Actions tab or gh run watch. Verify after the run:

docker run -p 8081:8081 yellowbean/hastructure:dev &
curl -s localhost:8081/version    # {"_version":"0.52.13"}

If a run failed for infrastructure reasons, re-trigger it with workflow_dispatch on "Docker Image CI Dev A Tag".

Release: binaries on the GitHub Releases page + latest image

just update-version 0.52.13
# add the CHANGELOG.md entry
just tag-files v 0.52.13         # same staging as above, tag v0.52.13
just upload-chlog                # scp CHANGELOG.md to the absbox.org website (needs the release key)

"Docker Image CI" then runs and publishes the GitHub Release automatically:

  • binaries attached as release assets, named Hastructure-v0.52.13-linux-amd64, ...-linux-arm64, ...-macos-arm64, ...-windows-amd64 — see Installation and Configuration
  • release created non-draft with auto-generated notes (gh release create --generate-notes), idempotent on rerun (gh release upload --clobber)
  • image pushed as yellowbean/hastructure:latest + :0.52.13 + :v0.52.13
  • Hackage upload runs in dry-run only (publish: false); a real Hackage publish needs the flag flipped and HACKAGE_KEY

Verify with gh release view v0.52.13 (assets + notes) and the docker pulls.

Historical drafts

Releases v0.44.0, v0.44.1, v0.45.7, v0.52.0 and v0.52.5 were created by the old workflow as drafts with assets named Hastructure-<version>-<OS>-ghc-<ghc>. They are invisible on the public Releases page until published one by one:

gh release edit v0.52.5 --draft=false

Housekeeping

  • revert a tag: just revert-tag <env> <version> (deletes the local + remote tag)
  • stage files manually: just tag-files stages CHANGELOG.md, app/Main.hs, Hastructure.cabal, swagger.json

Publishing to nixpkgs

nixpkgs builds Haskell packages straight from Hackage, so a nixpkgs presence starts with a real Hackage release:

  1. Release on Hackage. The release workflow only runs Hackage in dry-run (publish: false); a real upload needs HACKAGE_KEY and publish: true in hackage_dry_run (or a manual cabal upload --publish). Once on Hackage, the nixpkgs Haskell set (haskellPackages) mirrors it automatically through the periodic haskell-updates regeneration — no PR needed for the package to exist as haskellPackages.Hastructure.

  2. Expose the engine binary at top level (optional, recommended). A small pkgs/by-name/ha/hastructure/package.nix wrapper makes hastructure a top-level installable:

    # pkgs/by-name/ha/hastructure/package.nix
{
  symlinkJoin,
  haskellPackages,
}:

symlinkJoin {
  pname = "hastructure";
  version = haskellPackages.Hastructure.version;
  paths = [ haskellPackages.Hastructure ];
}

    Open a nixpkgs PR with this file (commits must carry the DCO Signed-off-by, git commit -s); after merge, users install with nix-shell -p hastructure or environment.systemPackages = [ pkgs.hastructure ].

  3. Faster alternative: build from the GitHub tag without a nixpkgs PR. For overlays/flakes or single users, callCabal2nix against the repo works today (this is what the repo's own release.nix does from a checkout):

    let
  pkgs = import <nixpkgs> { };
  src = pkgs.fetchFromGitHub {
    owner = "absbox";
    repo = "Hastructure";
    rev = "v0.52.13";            # pin to the release tag
    hash = "sha256-...";         # fill in from the first build
  };
in
pkgs.haskellPackages.callCabal2nix "Hastructure" src { }

Maintenance: when a new engine version is released, update the pinned rev in the nixpkgs wrapper's sources (with callCabal2nix-from-GitHub entries) or let step 1's automatic mirror do the work for haskellPackages.

Archive

all images were hosted in docker hub -> https://hub.docker.com/r/yellowbean/hastructure/tags

Clone this wiki locally