Release process

Current state: v1.0.0 publicly released and independently verified; repository reconciliation in progress

This document defines the protected release lifecycle around Cueson's repository-owned candidate proof and authorized public releases. It does not provide an executable publishing path or grant release authority by itself. The runnable candidate checks and independent v0.0.0 and v1.0.0 publication evidence are recorded in release verification.

Authority split

Candidate construction and verification are ordinary reviewed repository work. Final pull-request merge, tag creation or movement, tag push, GitHub Release publication, release-asset publication, milestone closure, immutable release-schema admission, and production cueson.io changes are distinct governed actions. Each action must remain within an approved release specification and must receive any explicit operator authorization required by the project constitution and AGENTS.md.

An authorization applies only to the named action and state under review. It does not silently authorize a later retry after material changes, another pull request, another tag, another release, or production publication.

v0.0.0 released state

The repository has a buildable 0.0.0 executable, an embedded 0.0.0 Cue JSON schema, a byte-identical immutable versioned release schema, published v0.0.0 release notes, and a verified non-publishing six-target snapshot pipeline. The current CLI and schema boundary is documented in the CLI contract and schema baseline.

The immutable annotated tag v0.0.0 peels to b294a6952c8bd041d852c502f5d7206c0b58edd6. The GitHub Release is public, final, and contains exactly six archives, six target-bound SPDX JSON SBOMs, and one checksum manifest copied byte for byte from accepted default-branch proof run 34543376814.

The release did not publish the canonical schema endpoint, add a signature or attestation, activate production cueson.io, implement native subtitle codecs, or itself close milestone v0.0.0. The milestone was closed only through later authorized reconciliation. GitHub Actions artifacts from later candidate runs remain review evidence rather than release assets unless another release is explicitly authorized.

Published v1.0.0 release

The immutable annotated tag v1.0.0 peels to 2cad4c816340404289b4d1d87179a4071713bb46. The GitHub Release is public, final, and contains exactly six archives, six target-bound SPDX JSON SBOMs, and one checksum manifest copied byte for byte from accepted default-branch proof run 34621429626.

S020 independently downloaded all thirteen files, matched their names, sizes, and SHA-256 values with the accepted contract, applied the six-archive checksum bijection, reran structural and semantic verification against the public bytes, and executed the Windows amd64 package. Publication did not host the schema at cueson.io, activate production configuration, add signatures or attestations, merge the S020 pull request, or close the v1 epic or milestone.

Candidate readiness

A release decision starts only from a clean, reviewed default-branch commit. Before asking for publication authority, maintainers must verify:

1. Every issue committed to the candidate is closed or truthfully moved, and the Project and milestone agree with that state.
2. The executable version, embedded schema version, and intended tag version are identical.
3. The detailed candidate history is complete under a dated section matching the intended version in CHANGELOG.md, with a fresh empty [Unreleased] section retained for later work.
4. Repository formatting, tests, race detection, vet, vulnerability analysis, CodeQL, platform-native tests, and pure-Go target builds are green.
5. The non-publishing snapshot and repository-owned verifier pass for the exact default-branch candidate commit and record its full revision plus release_schema_sha256 in deterministic evidence.
6. Documentation describes the candidate's actual commands and format-support declarations, distinguishes exact restoration from rendering and conversion, and contains no capability inherited from a different release.
7. No unresolved review or security finding remains.
8. The proposed release does not depend on an unapproved production-domain change.

Candidate readiness proves that a release decision can be made. It does not make the decision and does not grant permission to publish.

Release preparation lifecycle

For v0.0.0, S012 prepared the publication state without weakening the existing non-publishing controls.

1. The dated v0.0.0 changelog, concise release notes, and versioned release-schema candidate were reviewed together on the S012 pull request.
2. The complete six-target snapshot and repository-owned verifier proved the pull-request head as review evidence only because squash merge created a different commit.
3. The operator completed the final review and specific merge decision after the pull request was green and fully reviewed.
4. The main push workflow rebuilt and verified the exact squash-merge commit rather than substituting the pull-request head or pre-merge default-branch revision.
5. The default-branch release-evidence.json recorded the full source revision, version, release_schema_sha256, target inventory, archive and SBOM digests, counts, compatible-host execution result, and published: false.
6. S013 froze the complete decision package, received exact tag and release authority, published only the authorized state, and verified the public result independently.

The checked-in GoReleaser configuration remains snapshot-only and has publication disabled. A release slice must not repurpose that reviewed configuration into a hidden publication mechanism. S018 froze the v1 behavior without changing development identity. S019 promoted software, schema, and format maturity to the 1.0.0 stable candidate, admitted the immutable v1 schema, finalized the dated changelog and concise release notes, and proved the exact non-publishing candidate. S020 published and independently verified that exact candidate under explicit authority.

v1.0.0 candidate preparation lifecycle

1. S018 froze the intended v1 CLI, schema, SubRip, WebVTT, conversion, security, conformance, and documentation contracts at development identity 0.1.0.
2. S019 promotes the reviewed executable and schema identity to 1.0.0, changes only the completed SubRip and WebVTT format declarations to stable, and admits a byte-identical immutable repository schema.
3. The accumulated detailed history moves into a dated 1.0.0 changelog section, while concise candidate release notes retain the exact tagged changelog suffix and make no publication claim.
4. One six-target candidate bundle is built from the exact source revision, structurally verified, and executed on available native Linux, Windows, and macOS runners without publishing.
5. Pull-request evidence proves the reviewed head only. After a separately authorized squash merge, the main push proof must bind the resulting commit before issue #38 can request tag or release authority.
6. Public schema hosting, signatures, attestations, milestone closure, and production changes remain outside both S019 and the later GitHub Release transaction unless separately specified and authorized.

Pull-request and default-branch candidate binding

Pull-request proof answers whether the reviewed change can produce the expected candidate. It does not identify the final publication commit. Repository policy uses squash merges, so the pull-request head is not the resulting main revision and must never be recorded as the release target by prediction.

The non-publishing workflow also runs on pushes to main. After the authorized S012 merge, successful run 34543376814 promoted exact 40-character squash-merge revision b294a6952c8bd041d852c502f5d7206c0b58edd6 from reviewed repository state to the authorized publication target. Future releases must repeat this binding; if the default branch moves before authorization, or artifacts, tools, dependencies, notes, schema bytes, or checks change materially, the decision package must be regenerated and reviewed against the new state.

Operator decision package

Before requesting tag or GitHub Release authority, present the operator with one bounded package containing:

• the exact 40-character post-squash main commit proposed for the intended semantic-version tag;
• the intended version, dated changelog, and reviewed concise release notes;
• the lowercase release_schema_sha256 for the byte-identical canonical, versioned, embedded, and packaged schema;
• the exact six-archive and six-SBOM inventory, the six archive checksum entries, and every recorded archive and SBOM digest;
• the accepted release-evidence.json, including target identities, compatible-host execution result, and published: false;
• the green default-branch CI, CodeQL, and release-proof results plus the resolved review and security record;
• every capability limitation that applies to that candidate, plus the explicit absence of signatures, attestations, public schema hosting, or production activation unless those items were separately specified, proved, and authorized.

The operator decision must name the target commit and intended actions. Approval to create or push the tag does not authorize GitHub Release or asset publication, and approval to publish the release does not authorize production-domain work or milestone closure.

Protected publication actions

Authority for one row does not authorize another row. In particular, permission to merge a release-preparation pull request is not permission to create a tag or GitHub Release.

Tag and GitHub Release boundary

After release preparation reaches the verified default branch, the operator may authorize tag and release publication for the exact commit and artifact set recorded by the successful main proof. For v0.0.0, the operator authorized the exact S012 commit and thirteen public files, and S013 read back the resulting tag target, release notes, release state, and asset inventory before treating publication as complete.

The release must use the verified artifacts associated with the approved source commit. A rebuild from different source, a changed dependency, a changed tool version, or a materially different artifact set requires verification and operator judgment again. Draft, partial, or failed publication is not silently promoted to success.

Immutable schema boundary

The versioned repository schema, the schema embedded in every official binary, and the schema distributed in every release archive must be byte-identical. Their schema identity and version must match the release version.

After release, schema/releases/v0.0.0/cueson.schema.json and schema/releases/v1.0.0/cueson.schema.json are immutable. The v1.0.0 copy matches the canonical, embedded, emitted, and packaged schema byte-for-byte. Any correction now requires a new software and schema version; no path may overwrite an already released copy or move an existing tag to conceal the change.

The canonical https://cueson.io/schema/v0.0.0/cueson.schema.json and https://cueson.io/schema/v1.0.0/cueson.schema.json paths are published by the separately specified and authorized S021 production continuation. Their bytes must equal the immutable repository and release copies. Consumers may continue using embedded, repository, or release-artifact copies offline. No mutable schema alias is published.

Post-publication verification

Publication is complete only after read-back and independent comparison prove:

• the release tag identifies the authorized commit;
• the GitHub Release identifies the intended tag and is in the intended publication state;
• the published asset inventory is complete and contains no unexpected artifact;
• archive checksums match the published archives;
• every packaged executable contains the verified release marker and expected build identity, the host-compatible executable reports the release version, and every embedded schema reports the schema version;
• every packaged schema matches the immutable tagged repository schema byte-for-byte;
• SBOMs remain associated with the correct target and source revision;
• release notes are the reviewed highlights and end with the exact tagged changelog link;
• no production-domain state changed as a side effect.

If any comparison fails, stop dependent actions, retain the evidence, and ask the operator to choose a recovery path. Do not move a published tag, overwrite an immutable schema, replace assets, or close the milestone by inference.

Milestone lifecycle

S013 publication verification deliberately left the v0.0.0 milestone open because publication authority did not include milestone closure. A later separately authorized reconciliation closed it after the public release and repository record were verified.

The v1.0.0 milestone remains open after successful publication and independent post-publication verification. It may close only after the S020 delivery record merges and the operator separately authorizes epic and milestone lifecycle reconciliation.

For a future abandoned release, its milestone may be retired or its remaining commitments moved only through an explicit recorded decision. Repository status must continue to reflect the actual publication outcome.

After a successful release

After publication, maintainers retain the fresh [Unreleased] section for later work, preserve the released changelog and schema, complete post-merge housekeeping, and record any release follow-up as new issues rather than editing historical evidence. Milestone reconciliation follows only when separately authorized.

Signatures and attestations remain future outcomes. S021 separately specifies and authorizes public schema hosting, DNS, redirects, TLS, and documentation hosting; none was implied by the earlier snapshot verifier or the successful v0.0.0 and v1.0.0 GitHub releases.

Production site continuation

The reviewed S021 site change does not deploy from a pull request. After the human merge ritual, the operator or manual production workflow selects the exact merged main SHA, verifies that identity and all repository and site gates, then deploys the Worker and static artifact described in site/wrangler.jsonc. The deployment may configure only the cueson-site Worker and its cueson.io and www.cueson.io Custom Domains; unrelated Cloudflare resources remain untouched.

Production completion requires read-back of the Worker and Custom Domain state followed by independent public verification of DNS, trusted TLS, apex routes and metadata, permanent path-and-query-preserving www redirection, official release links, the deployed revision record, both immutable schema hashes and lengths, and absence of a latest schema. Failed propagation or certificate readiness is reported and diagnosed rather than treated as successful publication.