RELEASING.md

Releasing fgraph

One tag-triggered workflow proves the exact source, builds and smokes every archive, publishes the registries, and completes the GitHub release. A local green checkout is only a candidate.

1. Freeze the candidate

1. Confirm every runtime reports the same version with mise run check:versions.
2. Review docs/content/spec.md and the matching shared conformance cases.
3. Move user-visible changes from Unreleased to the dated version in CHANGELOG.md.
4. Confirm package, file-format, event, snapshot, and minimum-runtime compatibility.

2. Prove source and benchmark provenance

Benchmarks must identify a clean source commit. Use two commits because measuring necessarily changes the tracked benchmark outputs:

1. Commit the source, dependency, tool, specification, and benchmark-harness candidate.
2. From that clean commit, run mise run all, then mise run benchmark.
3. Review benchmarks/latest.ndjson, both SVGs, and the README tables. Commit only those generated observations and documentation updates.
4. From a clean checkout of the final commit, run mise run release:verify.
5. Push main and require green CI, Security, and Pages for that exact SHA.

Any source, dependency, tool, specification, or benchmark-harness change after measurement invalidates the benchmark digest and requires a new clean-source run.

3. Configure registries once

• Keep the GitHub release environment limited to v* tags.
• Configure PyPI trusted publishing for project fgraph, workflow release.yml, and environment release.
• Configure npm trusted publishing for package @fmind-dev/fgraph, repository fmind/fgraph, workflow release.yml, and environment release.
• Require two-factor authentication and disallow token-based publication in the npm package settings.

Both registries exchange GitHub's short-lived OIDC identity for publication credentials. Do not add registry tokens to GitHub, the repository, or the workflow.

4. Publish

Create both annotated tags on the proved commit and push them atomically:

git tag -a v1.2.0 -m "fgraph v1.2.0"
git tag -a go/v1.2.0 -m "fgraph Go module v1.2.0"
candidate="$(git rev-parse HEAD)"
test "$(git rev-list -n 1 v1.2.0)" = "$candidate"
test "$(git rev-list -n 1 go/v1.2.0)" = "$candidate"
git push --atomic origin v1.2.0 go/v1.2.0

The root tag starts .github/workflows/release.yml. The workflow:

1. reruns the clean release gate and verifies both tags;
2. builds deterministic Python, npm, and five native Go archives plus checksums;
3. executes every Go archive on its native runner;
4. enters the tag-limited release environment;
5. creates a draft GitHub release with the exact assets;
6. publishes npm and PyPI with Trusted Publishing, then makes the GitHub release public.

No approval or registry token is required after the two trusted publishers are configured.

Tags and registries are append-only. If a registry job fails after the draft is created, inspect that registry before retrying. When the version is definitely absent, rerun only failed jobs and their dependents with gh run rerun RUN_ID --failed; never rerun all jobs after draft creation because draft creation intentionally fails closed when the release already exists. If registry acceptance is partial or ambiguous, keep the draft, document the state, and fix forward with a patch version. Never republish immutable registry files or move a public tag.

5. Verify as a consumer

Test outside the checkout:

uvx --from fgraph==1.2.0 fgraph version
go install github.com/fmind/fgraph/go/cmd/fgraph@v1.2.0
npx --yes @fmind-dev/fgraph@1.2.0 --version

Download the release assets, verify SHA256SUMS, then run gh release verify v1.2.0 and gh release verify-asset v1.2.0 <artifact>. Create one database in each runtime, open it read-only from the other two, run doctor, and confirm the public docs and release links before announcing the release.