sandwich-hime/RELEASE.md

<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# Release process

Sandwich Hime uses separate root and runtime version lines. Compiler tags are
`vX.Y.Z`; runtime tags are `sando/vX.Y.Z`. Generated headers record both the
compiler version and runtime ABI. The runtime is always published before the
compiler that references it.

Every tag is immutable. A failed publication is corrected with a new version,
never by moving or replacing a tag.

## What the version stages mean

### Beta

A beta is an installable public evaluation release. The current
`v1.0.0-beta.1` scope is learning, classroom projects, prototypes, and
compatibility feedback. It receives best-effort security assessment and fixes
while it is the current prerelease, but it is not recommended or supported as a
production-stable dependency. Syntax, generated output, runtime APIs, CLI
behavior, and diagnostics may change in a later prerelease.

Beta 1 may publish with native macOS validation pending when Windows and Linux
have passed the exact-candidate matrix and macOS is clearly marked provisional.
Community Mac results are valuable compatibility input; they do not transfer
security review, triage, remediation, or release responsibility away from the
maintainers.

Beta tags are signed, annotated, and immutable. Beta 1 is a source/module
release installed through the Go toolchain; it does not promise downloadable
prebuilt binaries. Signed binary artifacts, checksums, SBOMs, reproducible
archives, and key-recovery rehearsal are mandatory for release candidates and
final v1.

### Release candidate

An RC means the intended v1 source, runtime, CLI, diagnostics, schemas, and
generated contract are frozen except for release-blocking fixes. An RC requires
maintainer-run native Linux, macOS, and Windows evidence, complete release
artifacts and provenance, signed tags, clean direct/proxy installs, and every RC
gate in this repository. Findings produce a new RC rather than a moved tag.

### Final v1

Final v1 is the compatibility and support commitment. It requires the complete
repository-owned evidence campaign, resolution or explicit acceptance of every
published assurance gap, and the documented RC observation period. A
deployment, example, classroom project, or case study in another repository is
neither imported nor required as release evidence.

## Beta 1 publication gates

Before `sando/v1.0.0-beta.1` and `v1.0.0-beta.1` are created:

1. Use a clean reviewed canonical public commit with no private identifiers,
   paths, credentials, or history.
2. Run license, root/runtime test, vet, build, race, deterministic-generation,
   and candidate-version freshness checks on supported Go 1.25 and Go 1.26
   lanes on Windows and Linux.
3. Confirm generated bytes match across those exact-candidate lanes and record
   all skips or platform limitations.
4. Run the bounded fuzz and known-vulnerability checks from a clean release
   host.
5. Review the changelog, security policy, compatibility policy, support scope,
   provisional macOS wording, and vanity-import metadata.
6. Build the candidate compiler at its candidate version and prove its committed
   generated fixtures are current under that exact binary.
7. Create signed annotated tags and publish the runtime tag first, then the
   compiler tag, from the same reviewed commit.
8. Verify both documented runtime-first installs from fresh `GOPROXY=direct`
   and public-proxy caches. Record propagation delays as delays, not test
   passes.

Beta 1 was published from public commit
`b7a84054d755e42285e50298e41e47f06a8325a5` (tree
`be9e118e38dfebed19f60403ededdadabe07d2aa`) after its exact-candidate
matrix passed. Future prereleases require their own candidate evidence; this
result cannot be relabeled for another commit.

## RC and final gates

No release candidate or v1.0.0 release occurs until every applicable gate in
this repository is evidenced, including cross-platform deterministic
generation, temporary-module compilation, fuzz/adversarial suites,
race/vet/vulnerability/license checks on the latest two supported Go lines,
development-supervisor failure tests, and reproducible repository-owned
benchmark and security results.

Release candidates require a clean canonical checkout, reviewed changelog,
compatible vanity-import metadata, reproducible binaries, signed annotated
tags, checksums, SBOMs, vulnerability results, and verification on Linux,
macOS, and Windows.

## Public source and artifacts

Gitea is the only canonical public forge. Public source is exported into a
separate, sanitized Gitea repository with fresh reviewed history. A sanitized
GitHub discovery snapshot may copy reviewed public source, but it is not an
issue, contribution, release, or module origin and must never receive private
development refs or an indiscriminate Git mirror. Release binaries and
provenance are built from the reviewed canonical Gitea commit.

The hosting configuration must answer exact package discovery requests, not
only module-root pages. In particular,
`/sandwich-hime/cmd/himesan?go-get=1` returns compiler metadata and the
`/sandwich-hime/sando` subtree returns runtime metadata. After tags and public
metadata exist, run:

```sh
scripts/verify-public-install.sh --version vX.Y.Z
```

That check adds the nested runtime before installing the parent compiler, then
exercises both commands from fresh direct-fetch and public-proxy caches. The
order avoids the Go module-cache ambiguity documented for Beta 1. It is
separate from the pre-tag, read-only `scripts/release-check.sh`.

Release notes report hardware, commit, datasets, commands, `ns/op`,
allocations, response latency, and methodology for any performance claim.
“Fastest” or equivalent language is prohibited without durable, reproducible
evidence.

Production applications compile and deploy their committed `.sando.go` files
with the Apache-2.0 `sando` runtime. They do not need the AGPL compiler or the
local development supervisor. Release checks verify that boundary without
executing or inspecting an unrelated application repository.