Venom
/SpecDocs
RFC-0008venom-spec

Zig version policy

Acceptedvenom-spec/rfcs/0008-zig-version-policy.md @ 81e1242
Field Value
Status Accepted
Authors commixon (commixon), with Codex
Created 2026-11-06
Accepted 2026-11-06, by the maintainer
Linear COM-200; README reference COM-240
Supersedes None
Superseded by None

Summary

Keep the ecosystem on one Zig release line, currently 0.17, with an exact compiler version in each repo’s .zigversion. Use a four-week upgrade window after each stable Zig release, enforced through tracked upgrade work, release-line checks in CI, and recorded dependency commits. Exact versions make builds reproducible; the upgrade window keeps them from becoming permanent. The maintainer accepted this policy under PROCESS.md on 2026-11-06.

Motivation

Shared Zig modules, libvaxis and libghostty-vt must build together. Independent release-line upgrades can break downstream consumers; an indefinite exact pin stops upgrades altogether. COM-205 already supplies .zigversion and a reusable workflow. This RFC defines how maintainers keep those mechanisms current.

Design

1. Release line and exact compiler

The canonical org-wide release line MUST be the default zig-pin input in venom-std/.github/workflows/zig.yml. It is 0.17 initially. A release line is major.minor; the repo pin is an exact stable major.minor.patch version:

0.17.0

Every ecosystem repo MUST contain .zigversion, including documentation repos so the toolchain selection is available consistently. A repo that has not yet been bootstrapped MUST add it before its first buildable implementation. The file MUST contain one version and a trailing newline, without comments. Patch versions MAY differ between repos on the same release line during an upgrade; the upgrade issues MUST record the tested compiler/dependency combinations. Pre-release compilers MAY be tested in non-gating experimental jobs but MUST NOT replace the stable pin without a separately reviewed policy exception.

Where build.zig.zon declares minimum_zig_version, it MUST use the shared release line and MUST NOT exceed the compiler selected by .zigversion. This field describes the minimum supported compiler; .zigversion selects the compiler installed for the build. A repo MUST NOT claim compatibility with an untested older compiler merely because it shares the release line.

2. CI enforcement

Buildable repos MUST use the reusable workflow or equivalent checks:

jobs:
  zig:
    uses: venom-org/venom-std/.github/workflows/zig.yml@main

CI MUST fail before the build when .zigversion is missing, malformed or outside the canonical release line. It MUST install the exact repo pin and fail when zig version differs from it. Builds, tests and format checks MUST run with that compiler. Existing workflow checks already cover the release line, compiler selection, build, tests and format; this RFC does not claim that every repo has adopted them yet.

A documentation-only repo MUST check the pin format and canonical release line when adding CI; it need not run Zig build/test steps. No CI check needs to discover the latest upstream release dynamically.

The workflow’s zig-pin override is for migration testing. Ordinary gating jobs MUST NOT silently use it to bypass the canonical line. Changing that default requires a reviewed venom-std upgrade PR and coordinated consumer PRs. For a breaking release-line transition, either prepare consumers against the candidate workflow revision or accept temporarily failing migration PR checks; do not turn off version checks to make an incompatible build green.

3. Four-week upgrade window

For each upstream stable Zig release, the maintainer MUST open an upgrade tracking issue within seven calendar days. The deadline is 28 calendar days after the upstream release date, for both patch releases and new release lines. Development snapshots do not start a deadline.

The tracking issue MUST carry the zig-upgrade label, record the upstream release date, target compiler, deadline and owner, and link one issue per repo that needs a change. Each repo issue MUST name its project and milestone, state testable “Done when” criteria, and link blocking dependencies across repos. A repo already on the target compiler needs verification recorded in the tracker, not an empty upgrade PR.

Upgrade in dependency order: spec/policy and shared workflow, venom-std and venom-term, product consumers, then venom-os. Prepare PRs in parallel where possible, but merge dependent package pins after their prerequisites. Run each repo’s documented checks and the shared conformance suite where adopted. Update .zigversion, minimum compiler declarations, dependency pins and the compatibility record together in the relevant PRs.

If an upstream dependency or required target prevents adoption by day 28, the maintainer MUST approve a dated exception in the tracking issue before the deadline. Record the blocker, affected repos, retained versions and next review date, at most 14 days later. An agent MUST NOT grant an exception. Revisit it at each review date until the upgrade ships. Superseding releases do not silently erase an overdue tracker; explicitly close or retarget it.

4. Known-good terminal dependencies

venom-term owns the libvaxis and libghostty-vt pins. Products MUST depend on venom-term rather than pinning those libraries themselves. For each compiler version used in gating CI, venom-term MUST record a compatibility row in its docs containing:

Field Required value
Zig Exact compiler version from .zigversion
libvaxis Full upstream commit and package hash from build.zig.zon
libghostty-vt Full upstream commit and package hash from build.zig.zon
Evidence Wrapper commit/PR, test command, platform and result

Keep previous rows when upgrading so a known-good combination can be restored. Branches, moving tags and “latest” are not sufficient pins. A package hash verifies downloaded content; it does not replace recording the upstream commit. Passing the wrapper build alone is not enough: run VT/row-addressing tests, consumer tests and pane examples/measurements required by venom-term’s repo instructions. Record an unsupported target explicitly rather than implying it passed. This RFC establishes the record format; it does not certify any particular dependency combination or ship compiler/dependency changes.

Agent-contract impact

  • Verbs and verb schemas: no change; this is a development policy.
  • --json output and exit codes: no change.
  • events --json: no change.
  • skill, doctor, and config get|set|check|reload|schema: no change.
  • Capability grants and read-only defaults: no change.
  • Headless operation and OSC 7501 / OSC 133: no change.

Alternatives

  • Do nothing / pin forever: reproducible today, but no owner or deadline moves the ecosystem forward when Zig or dependencies change.
  • Unbounded compiler ranges: convenient locally, but do not reproduce CI failures and cannot identify which terminal dependency commits were tested.
  • One exact patch required everywhere at every moment: makes coordinated upgrades unnecessarily atomic. A shared release line plus exact repo pins allows staged patch adoption with a common deadline.
  • Upgrade on release day: leaves no time to validate upstream dependencies. Four weeks provides a bounded validation period; explicit exceptions expose blockers instead of turning the target into an indefinite promise.

Open questions

None unresolved. The maintainer accepted the four-week window and exception process on 2026-11-06. Adoption work in repos without pins, CI or compatibility records follows through separate zig-upgrade issues; this document and COM-240 provide the policy and README reference, not a claim that rollout has already completed.