Releasing

This page says what a PEGO 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.

PEGO has no tagged release yet.

#What a v0.x Release Promises

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

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

#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 (including the pego fix rewrite where one exists), then new features and fixes.

#Supported Platforms

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

PEGO requires Go 1.27.1 or later, and so does the Go code it generates. That covers the pego command, the engine API and generated Go with either runtime: the default -runtime embed, which copies the runtime into the generated package, and -runtime import, which makes the consumer depend on the PEGO module. Generated Go is required to build with Go 1.27.1 or later; no lower version is promised.

Recording pego as a tool raises the module's go line to 1.27.1. go get -tool github.com/ornew/pego/cmd/pego (github.com/pego-lang/pego/cmd/pego once the repository has moved; see Tagging a Release) adds the PEGO 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 the one in force at the time: github.com/pego-lang/pego once the repository has moved (step 2).

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

2. For the first release only, move the repository to the pego-lang GitHub organization:

   • transfer the repository from github.com/ornew/pego to github.com/pego-lang/pego, and point the origin remote of each checkout at the new address;
   • change the module path to github.com/pego-lang/pego in every go.mod of the repository and in every import path and document that names it;
   • regenerate the generated files with go generate ./parsers ./bench;
   • run the full suite, as in step 4;
   • update the site (repository in site/config.json) and the Netlify configuration (the repository that the Netlify site builds from);
   • enable private vulnerability reporting for the new repository, so that the route in SECURITY.md works;
   • commit the change to main.

   After the first release, the ready-made parsers may move to their own repositories under the organization.

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 ./parsers ./bench && git status --short   # generated files are current: prints nothing
   parsers/test.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 PEGO against the current benchmark report; rerun the benchmarks only if the report is older than the changes it describes. From the first release, pego gen generates parsers with work controls by default (today -work-controls turns them on), and published performance figures are measured with the limits on.

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 with an annotated tag and push the tag:

   git tag -a vX.Y.Z -m "PEGO 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 github.com/pego-lang/[email protected]
    

11. Publish the release notes on the GitHub release of the tag.