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.

Current and future beta release gates run on Linux/amd64. WSL may be used as a
Linux development environment, but native Windows, macOS, and other targets
are not release blockers or maintained compatibility promises. Portability
reports remain useful 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 Linux/amd64 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 (historical)

The first beta used a broader one-time platform campaign. The completed items
below are retained as publication history; they do not define future platform
support.

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.

## Beta 2 compiler publication gates

`v1.0.0-beta.2` is compiler-only. Do not create or move a runtime tag when the
`sando` subtree is byte-identical to `sando/v1.0.0-beta.1`.

Run its technical preflight with the retained runtime made explicit:

```sh
./scripts/release-check.sh \
  --version v1.0.0-beta.2 \
  --runtime-tag sando/v1.0.0-beta.1
```

In addition to every Beta 1 compiler/security/determinism gate:

1. verify protocol framing, malformed messages, shutdown, request
   cancellation, UTF-16 positions, CRLF/NUL handling, bounded fuzz smoke,
   overlays, source appearance/deletion, duplicates, cycles, symlink and
   nested-module boundaries, completion scope, and component definitions;
2. prove the language-server package does not write, execute project code,
   invoke Go, fetch, access the network, or start the development supervisor;
3. run the exact candidate on supported Go lines under executed Linux/amd64;
4. build an exact version-stamped candidate and assert the additive
   `features: ["lsp-stdio"]` JSON identity;
5. publish a signed annotated compiler tag only after the reviewed sanitized
   public commit is current; and
6. verify direct, public-proxy, and checksum-database installation without
   altering `v1.0.0-beta.1` or `sando/v1.0.0-beta.1`.

## RC and final gates

No release candidate or v1.0.0 release occurs until every applicable gate in
this repository is evidenced, including deterministic generation on supported
Linux and Go lanes, 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 Linux/amd64 binaries, signed
annotated tags, checksums, SBOMs, vulnerability results, and verification on
Linux/amd64.

## 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.