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
ProtocolNfor each protocol version N it implements. - A parser generated with
-lib importrefers 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/impldeclares exactly one constantProtocolN, 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 avalue/implpackage that do not match therefore fail to build (undefined: valueimpl.Protocol15), in either direction. A test ofvalueimplrecords 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
retractdirective in thego.modof 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.
-
Check that the release items of the project strategy are done.
-
The repository lives in the
syntaxirGitHub organization, atgithub.com/syntaxir/syntaxir, and its module path issyntaxir.dev/sxir. The site servesgo-importandgo-sourcemeta tags so that each import path of the repositories listed insite/vanity.goresolves 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-importIt 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 assyntaxir.dev/alpha-parsers. -
Start from a clean checkout of
mainat the commit to tag:git switch main && git pull --ff-only && git status --short # prints nothing -
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 -
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.
-
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 gengenerates parsers with limit controls by default (-no-limitsopts out), and published performance figures are measured with the limits on; a figure measured on the form without them says so. -
Update the resource policy of SECURITY.md to the defaults that this release ships.
-
Write the release notes (Announcing Changes).
-
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.ZSigning the tag (
git tag -sin place ofgit 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. -
Ask the Go module proxy for the new version, so that
go getand pkg.go.dev see it:GOPROXY=https://proxy.golang.org go list -m syntaxir.dev/sxir@vX.Y.Z -
Publish the release notes on the GitHub release of the tag.