Skip to content

RELEASING.md

Latest commit

 

History

History
152 lines (115 loc) · 6.35 KB

RELEASING.md

File metadata and controls

152 lines (115 loc) · 6.35 KB
Raw

Releasing C2Go Toolchain

简体中文

This procedure is fail-closed. A locally prepared checkout, an unpushed commit, or a passing component-only test is not release evidence.

1. Publish the component repositories

Create and populate these controlled repositories first:

  • https://github.com/c2gohq/c2go_clang.git
  • https://github.com/c2gohq/c2go_bind.git
  • https://github.com/c2gohq/c2go_libc.git
  • https://github.com/c2gohq/musl.git

The c2go-clang fork must not use the upstream LLVM repository as its push target. Preserve upstream history and all LLVM notices.

Before adding submodules, verify that every release commit is reachable from its public remote and that c2go-libc pins the intended musl commit as its own nested submodule.

2. Initialize the top-level submodules

The submodules are already registered in .gitmodules. From a fresh checkout:

git submodule sync --recursive
git submodule update --init --recursive

Check out reviewed, immutable commits in each component. Never point a release at a moving branch name.

3. Close component release blockers

At minimum, verify from clean recursive clones:

  1. c2go-clang builds the coordinated compiler and passes the selected Clang, LLVM, C2Go, and cross-repository tests.
  2. c2go-bind passes tests, race tests, vet, build, and cross-repository LIT.
  3. c2go-libc contains or no longer requires c2go_libc/dl, has a real musl submodule, ships or reproducibly generates every promised target artifact, and passes the reviewed platform matrix.
  4. All Apple/FreeBSD/XNU/MinGW/musl/Go/PureGo and other provenance boundaries, notices, and complete-source obligations are closed.
  5. The commercial licensor, contributor agreement, and public contact/payment process are legally ready without changing third-party rights.

4. Lock the release

Use one coordinated version and the same tag in all three top-level components. Coordinated releases use:

vMAJOR.YYYYMMDD.REVISION[-rc.N]
  • MAJOR is the compatibility line. Keep it at 0 while the public contract remains pre-1.0.
  • YYYYMMDD is the UTC date on which the coordinated release line is cut.
  • REVISION starts at 0. Increment it for an additional maintenance release on that same date, such as a post-release correction.
  • -rc.N identifies successive candidates for the same base version. Candidate fixes advance N; remove the suffix only when promoting the exact final candidate snapshot to stable.

For example, candidate fixes advance from v0.20260729.0-rc.1 to v0.20260729.0-rc.2. The corresponding stable version is v0.20260729.0; a same-day maintenance release starts at v0.20260729.1-rc.1. Exact component and dependency revisions belong in the lock file, not in the version string.

This CalVer-in-SemVer form keeps the coordinated tag usable by the unsuffixed Go module paths. Do not use vYYYY.MM.DD: zero-padded month/day fields are not valid SemVer numeric identifiers, and a year in the SemVer major position would require matching /vYYYY Go module paths. The first proposed public candidate is v0.20260729.0-rc.1. Before advancing MAJOR beyond 1, either migrate the Go module paths to their required /vN suffixes or explicitly decouple component tags from the toolchain tag.

Update toolchain.lock.json:

  • set release.version, release.status, and release.published_at;
  • set every component and nested dependency to its full commit hash and tag;
  • update the Go version window and C2Go ABI epoch only from verified evidence;
  • commit the resulting submodule gitlinks and lock file together.

Prepare the English GitHub Release body as RELEASE_NOTES/<version>.md. A Chinese companion may be stored as RELEASE_NOTES/<version>.zh-CN.md. A tagged workflow fails if the English release note is missing.

5. Run the release gate

From a clean recursive clone of this repository:

git submodule update --init --recursive
python3 scripts/verify-release.py

Then run the documented component build/test matrix. Preserve machine-readable logs with the release evidence.

After pushing the reviewed commits (but before creating tags), run the Release C2Go toolchain workflow manually with the candidate version. This is an unsigned dry run: it exercises the same four native build jobs and complete source packaging without creating a GitHub Release.

6. Build release artifacts

A Git archive of this repository does not include submodule contents. Build a complete release source bundle that contains or fetches, in a license-compliant and reproducible way, every exact component and nested dependency used to build shipped artifacts.

Keep platform SDKs distinct from that source bundle. A platform SDK must be an installed, relocatable tree containing bin/, public include/, required lib/ runtime resources, licenses/, and release metadata. It must not contain repository mirrors, tests, build scripts, or component source trees. Before upload, extract each SDK and run scripts/verify-package.py on its native builder; do not validate tools from the build directory in place of the archive.

For every binary/source bundle, publish:

  • filename, platform, architecture, and toolchain version;
  • SHA-256 checksum;
  • exact component and nested-dependency revisions;
  • applicable license and third-party notice bundle;
  • reproducible build instructions and required bootstrap tools; and
  • SBOM/provenance data when available.

The checked-in workflow currently uses Ubuntu 22.04 for both Linux architectures, Windows Server 2022 for Windows amd64, and macOS 14 arm64 with CMAKE_OSX_DEPLOYMENT_TARGET=11.0. It emits unsigned deterministic archives, the complete recursive source bundle, checksum sidecars, and SHA256SUMS. Signing, Apple notarization, and Windows Authenticode are deliberately not configured until the corresponding credentials and policy are available.

7. Tag and publish

Tag reviewed component commits first. Then tag the c2go-toolchain commit whose gitlinks and lock file reference those exact commits. Pushing that tag builds the assets and creates a GitHub Release draft using the repository's automatic GITHUB_TOKEN; no personal access token is required. Inspect the artifacts, rendered notices, checksums, and installation smoke tests, then publish the draft manually.

Do not move or replace a published tag. Corrections receive a new candidate or patch version.