Releasing

This page says what a SyntaxIR release promises, which platforms and Go versions it supports, and how a release is tagged. It is written for maintainers who cut a release and for users who decide whether to depend on one. The vulnerability policy is in SECURITY.md.

SyntaxIR has no tagged release yet.

What a v0.x Release Promises

Go modules give a v0 version no compatibility guarantee. SyntaxIR states its intent for each surface instead.

Surface At v0.x
The grammar language: .sxir syntax and meaning (specification) Stable in intent. A change that breaks a grammar is announced with how to update the grammar
The API of generated Go parsers (Parse, ParseValue, the options and the error types) Stable in intent. A generated parser carries the library of the generator that produced it, so regenerate it after upgrading SyntaxIR
The module API, including the pkg/compiler, pkg/runtime and pkg/grammar packages May change in any release; changes are announced
The testing packages sample (input generation) and editfuzz (incremental-parsing fuzzing), and the sequence files of editfuzz Public so that Go programs can test their own grammars and documents; unstable: may change in any release
The fixture suites of sxir test (the JSON format) Unstable: may change in any release; the runner is internal, not a Go API
The packages syntaxir.dev/sxir/pkg/runtime, syntaxir.dev/sxir/pkg/runtime/value, syntaxir.dev/sxir/pkg/runtime/input and syntaxir.dev/sxir/pkg/runtime/instrument: the nodes, limits, positions, errors, edits and statistics that sxir and generated Go parsers share Stable in intent, as part of the API of generated parsers
The packages syntaxir.dev/sxir/pkg/runtime/libgo and syntaxir.dev/sxir/pkg/runtime/value/impl, as generated code uses them with sxir gen -lib import Not a stable API. Judged by the protocol version (see the library protocol), not by the release version
Compiled grammars (.sxirc) and the bytecode: container version 8, instruction-set version 38 (bytecode specification) Unstable: may change in any release. A loader accepts only its own versions and asks for the grammar to be compiled again
The JSON forms of grammars and nodes Unstable: may change in any release
Ready-made parsers (syntaxir.dev/alpha-parsers) Not part of a release: a separate repository, used from a checkout next to this one with a go.work

"Stable in intent" means that a change needs a reason and is announced; it is not the compatibility guarantee of a v1 module.

The Library Protocol

The library of generated Go parsers is the package syntaxir.dev/sxir/pkg/runtime/libgo in the directory pkg/runtime/libgo/, released with the module syntaxir.dev/sxir. Which parsers a library can serve is decided by the protocol version: a number that names one state of the interface between generated code and the library, independent of the release version. The interface is the exported declarations of the library package, the exported fields and methods of the types they reach, and what they mean, including the encoding of the data generated parsers pass to the library.

  • The library declares a constant ProtocolN for each protocol version N it implements.
  • A parser generated with -lib import refers to the constant of the protocol it was generated for, so a parser and a library that do not match fail to build (undefined: rt.Protocol30), never at run time.
  • The package syntaxir.dev/sxir/pkg/runtime/value/impl declares exactly one constant ProtocolN, where N is the protocol version that introduced the node representation it serves, and the library refers to that constant. A copy of the library embedded in a generated parser and a value/impl package that do not match therefore fail to build (undefined: valueimpl.Protocol15), in either direction. A test of valueimpl records the representation (the layout of its types, the values of its constants and the signatures of its functions) with the constant, and fails when the representation changes while the constant does not.
  • The protocol version increases whenever that interface changes; a test of the library compares the declarations with the ones recorded for the current version and fails otherwise. A change of meaning or data encoding that keeps the declarations needs the same increase, and no test detects it.

A release whose library keeps the protocol serves the parsers generated by earlier releases of that protocol; a release that changes it needs the parsers regenerated. The release notes say whether the protocol changed. The header of a generated file (// Code generated by sxir vX.Y.Z. DO NOT EDIT.) names the version of its generator, which is how security advisories name affected parsers: a tag for a release, a pseudo-version for a build from a commit, (devel) for a build that has no reproducible identity (a modified tree, a replaced module, go run).

Version Numbers

Releases are tagged with semantic versions, vMAJOR.MINOR.PATCH, as Go modules require. The first release is v0.1.0.

  • Before v1, a minor version may change a surface that is stable in intent, with an announcement.
  • A patch version fixes defects and changes no surface that is stable in intent.
  • A release that turns out to be broken is retracted with a retract directive in the go.mod of the next release; a published version cannot be removed from the Go module proxy.

Announcing Changes

Each release has release notes on its GitHub release page; the repository keeps no separate changelog file. The notes list breaking changes first, each with what to do, then new features and fixes.

Supported Platforms

Platform Status
macOS on Apple silicon (darwin/arm64) Tested: the repository tests and the benchmarks run on it
Linux on x86-64 (linux/amd64) Tested by the continuous-integration workflow when it runs. Workflows are paused at present, so a release runs the checks on linux/amd64 before it is tagged
WebAssembly (js/wasm) Tested: the playground's WebAssembly build has a smoke test under Node.js, which runs when Node.js is installed
Windows Not tested. The module builds and passes go vet for windows/amd64
32-bit platforms Not supported. The module builds for linux/386, but known integer-overflow defects on 32-bit platforms are open; the work is deferred

Generated TypeScript is tested under Node.js: the continuous-integration workflow uses Node.js 22.18.0, and the benchmarks run it under Node.js 24.13.0. It is written to run in Deno, Bun and browsers, but no test runs it there.

Go Versions

SyntaxIR requires Go 1.27.1 or later, and so does the Go code it generates. That covers the sxir command, the compiler and runtime API and generated Go with either library mode: the default -lib embed, which copies the library into the generated package, and -lib import; with both, the consumer depends on the SyntaxIR module for its pkg/runtime packages. Generated Go is required to build with Go 1.27.1 or later; no lower version is promised.

Recording sxir as a tool raises the module's go line to 1.27.1. go get -tool syntaxir.dev/sxir/cmd/sxir adds the SyntaxIR module as a dependency, and because that module requires Go 1.27.1, the go command raises the consumer module's go line to match (go: upgraded go 1.23 => 1.27.1). This is expected: the generated code needs the same version.

Tagging a Release

In the commands below, vX.Y.Z is the version being released and the module path is syntaxir.dev/sxir.

  1. Check that the release items of the project strategy are done.

  2. The repository lives in the syntaxir GitHub organization, at github.com/syntaxir/syntaxir, and its module path is syntaxir.dev/sxir. The site serves go-import and go-source meta tags so that each import path of the repositories listed in site/vanity.go resolves to its repository in the organization (see Go vanity imports). Before the first release, check that the deployed site serves them:

    curl -sL 'https://syntaxir.dev/sxir/cmd/sxir?go-get=1' | grep go-import
    

    It prints <meta name="go-import" content="syntaxir.dev/sxir git https://github.com/syntaxir/syntaxir">. Also check that private vulnerability reporting is enabled for the repository, so that the route in SECURITY.md works.

    The ready-made parsers are in their own repository, github.com/syntaxir/alpha-parsers, which the site serves as syntaxir.dev/alpha-parsers.

  3. Start from a clean checkout of main at the commit to tag:

    git switch main && git pull --ff-only && git status --short   # prints nothing
    
  4. Run the checks of the development guide:

    go test -timeout=30m ./...
    go generate ./bench && git status --short   # generated files are current: prints nothing
    hack/test-alpha-parsers.sh
    (cd site && go test -count=1 ./...) && site/build.sh
    
  5. Run the checks of step 4 on linux/amd64 as well, on a Linux machine or by a run of the continuous-integration workflow. While workflows are paused, this run is a precondition of the release.

  6. Check the figures in the README and in Why SyntaxIR against the current benchmark report; rerun the benchmarks only if the report is older than the changes it describes. sxir gen generates parsers with limit controls by default (-no-limits opts out), and published performance figures are measured with the limits on; a figure measured on the form without them says so.

  7. Update the resource policy of SECURITY.md to the defaults that this release ships.

  8. Write the release notes (Announcing Changes).

  9. Tag the commit checked in steps 3 to 5 with an annotated tag and push it:

    git tag -a vX.Y.Z -m "SyntaxIR vX.Y.Z"
    git push origin vX.Y.Z
    

    Signing the tag (git tag -s in place of git tag -a) is optional. When workflows are enabled, pushing the tag starts the continuous-integration workflow. The local checks of steps 4 and 5 are the release gate either way.

  10. Ask the Go module proxy for the new version, so that go get and pkg.go.dev see it:

    GOPROXY=https://proxy.golang.org go list -m syntaxir.dev/sxir@vX.Y.Z
    
  11. Publish the release notes on the GitHub release of the tag.