199 lines
9.1 KiB
Markdown
199 lines
9.1 KiB
Markdown
<!-- 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 and Beta 2 retain their historical platform evidence. The v1 RC line
|
|
raises the maintained release gate to native Linux/amd64 and Apple Silicon
|
|
macOS/arm64. WSL, native Windows, Intel macOS, and other targets remain useful
|
|
portability input but are not v1 release blockers or maintained promises.
|
|
|
|
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 and native macOS/arm64 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 and Darwin/arm64
|
|
binaries, signed annotated tags, checksums, SBOMs, vulnerability results, and
|
|
verification on both maintained native targets. Darwin artifacts additionally
|
|
require manual Developer ID signing, notarization, stapling, and Gatekeeper
|
|
validation outside runner authority.
|
|
|
|
Human-reviewed RC evidence stays outside the source tree. After completing the
|
|
fixed document set reported by `himesan-release verify-evidence`, the release
|
|
operator seals its exact bytes and source identity once:
|
|
|
|
```sh
|
|
go run ./cmd/himesan-release evidence-manifest \
|
|
--directory "$HIMESAN_RELEASE_EVIDENCE_DIR" \
|
|
--repository gamertan/sandwich-hime \
|
|
--version v1.0.0-rc.1 \
|
|
--commit "$(git rev-parse HEAD)" \
|
|
--tree "$(git rev-parse 'HEAD^{tree}')" \
|
|
--reviewed-by "REVIEWER" \
|
|
--reviewed-at "YYYY-MM-DDTHH:MM:SSZ"
|
|
```
|
|
|
|
The manifest is created without overwrite. Changing any document or candidate
|
|
identity requires a fresh review directory and manifest; deleting a manifest
|
|
is not an approval shortcut. `release-check.sh --public` verifies the sealed
|
|
digests and identities but never substitutes for the human review itself.
|
|
|
|
Native receipts use an equally strict, extraction-scratch-free layout. Download
|
|
runner ZIPs outside this directory, then copy only each checksummed receipt pair
|
|
into the exact four lanes:
|
|
|
|
```text
|
|
$HIMESAN_NATIVE_EVIDENCE_DIR/
|
|
├── darwin-arm64-go1.26.7/TEND-CI-VERIFICATION.json{,.sha256}
|
|
├── darwin-arm64-go1.27.0/TEND-CI-VERIFICATION.json{,.sha256}
|
|
├── linux-amd64-go1.26.7/TEND-CI-VERIFICATION.json{,.sha256}
|
|
└── linux-amd64-go1.27.0/TEND-CI-VERIFICATION.json{,.sha256}
|
|
```
|
|
|
|
ZIPs, additional files, renamed lanes, development-repository identities, and
|
|
receipts for a public commit other than current canonical `main` are rejected.
|
|
The strict layout prevents extraction debris or a nearby historical run from
|
|
being mistaken for the reviewed native receipt set.
|
|
|
|
## 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.
|