Development and Release

Development and Release

This page covers local development, validation, profiling, CI, and release operations.

Environment

Main stack:

• Go 1.26.4
• Fiber v3
• dix for dependency injection and lifecycle
• collectionx, lo, and mo for collection and option helpers
• gocron for scheduled internal tasks
• observabilityx for metrics integration
• GoReleaser for GitHub Release assets and Linux packages
• Docker Buildx for GHCR and Docker Hub images

Common development commands

task test
task lint
task check
task build

• task test: runs go test ./....
• task lint: runs golangci-lint run ./....
• task check: runs staticcheck.
• task build: builds the current-platform runtime binary.

Benchmark and profiling

task perf:bench
task perf:bench:static
task perf:k6
task perf:k6:frontend
task perf:k6:split
task perf:aot:refine:baseline

Profile commands:

task perf:profile:resolver
task perf:profile:cache
task perf:profile:pipeline
task perf:profile:http
go tool pprof .\tmp\perf\http.cpu.pprof

The k6 tasks require Docker. They build benchmark images and run SPACK direct, SPACK AOT, Nginx, and k6 containers.

CI

The GitHub Actions CI workflow runs on push and pull request:

• Go setup from go.mod
• install Task
• task lint
• task check
• task test
• task build

CI currently covers:

• ubuntu-latest
• windows-latest

Tag-driven release

Normal release flow is tag-driven:

task release VERSION=2.0.5

Or use automatic version bumps:

task release:bump:patch
task release:bump:minor
task release:bump:major

Tags use the vX.Y.Z format.

Local release flow

When GitHub Actions cannot run, use the local release workflow:

task release:local

The task runs scripts/release-local.sh through Goyek. It performs:

• Builds a Linux release runner image from docker/release-runner.Dockerfile.
• Runs GoReleaser inside Linux with --skip=docker for GitHub Release archives and Linux packages.
• Prepares the Docker build context from dist/.
• Pushes runtime Debian images.
• Pushes compiler Debian images.
• Pushes runtime Alpine images.
• Verifies image manifests and GHCR package visibility.

Useful variables:

Variable	Default	Meaning
SPACK_RELEASE_TAG	latest v* tag	Release tag to publish.
SPACK_RUNTIME_PLATFORMS	linux/amd64,linux/arm64	Runtime Debian platforms.
SPACK_COMPILER_PLATFORMS	linux/amd64	Compiler Debian platforms.
SPACK_ALPINE_PLATFORMS	linux/amd64	Runtime Alpine platforms.
SPACK_PUSH_GHCR	true	Push GHCR tags.
SPACK_PUSH_DOCKER_HUB	true	Push Docker Hub tags.

Release verification

After publishing, run:

task release:verify

The task runs scripts/release-verify.sh through Goyek. It verifies the published images instead of local images. Compiler-side image variant generation is disabled by default for speed, but can be enabled with SPACK_IMAGE_ENABLE=true, SPACK_IMAGE_WIDTHS, and SPACK_IMAGE_FORMATS when validating an image matrix:

• Inspect runtime, compiler, and Alpine manifests.
• Compile a fixture dist directory with the published compiler image.
• Verify the generated .spack bundle.
• Start direct runtime and AOT runtime containers with read-only root filesystems and dropped capabilities.
• Check /livez, HTML, JavaScript, Range requests, and browser-like image requests.
• Confirm invalid external .gz sidecars are not trusted as gzip responses.

Release artifacts

GoReleaser publishes:

• GitHub Release archives
• checksums.txt
• Linux deb, rpm, and apk packages
• Runtime archives for Linux, macOS, and Windows
• Compiler archive for Linux amd64

Images:

ghcr.io/lyonbrown4d/spack
lyonbrown4d/spack
ghcr.io/lyonbrown4d/spack-compiler
lyonbrown4d/spack-compiler

Tags:

Repository	Tag	Description
spack	latest	Debian slim runtime latest.
spack	<version>	Debian slim runtime version.
spack	debian	Debian slim runtime latest.
spack	debian-<version>	Debian slim runtime version.
spack	alpine	Alpine runtime latest.
spack	alpine-<version>	Alpine runtime version.
spack-compiler	latest	Debian slim compiler latest with libvips runtime libraries.
spack-compiler	<version>	Debian slim compiler version with libvips runtime libraries.
spack-compiler	debian	Debian slim compiler latest with libvips runtime libraries.
spack-compiler	debian-<version>	Debian slim compiler version with libvips runtime libraries.

v2.0.5 release record

• Release: https://github.com/lyonbrown4d/spack/releases/tag/v2.0.5
• Runtime Debian digest: sha256:e7a23b4bc3f64ce5cbf06b1ddd754557796eaeb44a035e23d607c60cd6ed77bb
• Runtime Alpine digest: sha256:16298d065a24421dacdba4446822e734c1c0cb2fa34fbaca30b299151d1d2536
• Compiler Debian digest: sha256:5823a000b3a05024abc09c7803a745bdff29be030f94afecada517f9bc937d71

v2.0.5 was published locally because GitHub Actions was not available. GitHub Release assets were generated by GoReleaser in a Linux container; images were pushed with Docker Buildx from Docker Desktop.

Contribution rules

• Prefer dix module/lifecycle for dependency wiring.
• Prefer collectionx, lo, and mo for collection-oriented simplification.
• Wrap errors with oops and keep useful context.
• Do not bypass lint issues with nolint or lint configuration changes.
• Avoid exposing internal scheduler details as user configuration.
• Performance changes should add benchmarks or at least run the relevant profiles.