<!-- Canonical source: https://github.com/deancochran/ftms/blob/2586e33ac88d5d945d9658e063bb909cd58462bd/docs/releasing.md; revision: 2586e33ac88d5d945d9658e063bb909cd58462bd -->

# Releasing FTMS packages

Packages are independently versioned; a version in one package does not imply a release of another. Prepare locally, review and merge the change, create the explicit tag on the reviewed `main` commit, verify artifacts, publish, then verify public artifacts and an installed consumer.

| Package / runbook                                                                         | Tag                                                | Workflow                                                       | Publication                                                                             |
| ----------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [TypeScript](https://deancochran.github.io/ftms/reference/typescript/index.md#release)    | `typescript-vVERSION` for 1.0+; `vVERSION` for 0.x | `publish.yml`                                                  | npm (`next` for prereleases)                                                            |
| [Python](https://github.com/deancochran/ftms/blob/main/packages/python/RELEASING.md)      | `python-vVERSION`                                  | `release-python.yml`                                           | PyPI trusted publishing                                                                 |
| [Kotlin](https://github.com/deancochran/ftms/blob/main/packages/kotlin/docs/releasing.md) | `kotlin-vVERSION`                                  | `release-kotlin.yml`                                           | Maven Central                                                                           |
| [Rust](https://github.com/deancochran/ftms/blob/main/packages/rust/docs/releasing.md)     | `rust-vVERSION`                                    | `release-rust.yml`                                             | crates.io                                                                               |
| [Swift](https://github.com/deancochran/ftms/blob/main/packages/swift/RELEASING.md)        | `swift-vVERSION`                                   | `release-swift.yml`                                            | GitHub source/evidence release; SwiftPM revision pins                                   |
| [C](https://github.com/deancochran/ftms/blob/main/docs/releasing-c.md)                    | `c-vVERSION`                                       | `release-c.yml`                                                | GitHub source release; Conan/vcpkg submissions are separate                             |
| [Dart](https://github.com/deancochran/ftms/blob/main/packages/dart/RELEASING.md)          | `dart-vVERSION`                                    | `release-dart.yml`                                             | pub.dev; first manual bootstrap, then protected tag/OIDC publishing                     |
| [C#](https://github.com/deancochran/ftms/blob/main/packages/csharp/docs/releasing.md)     | `csharp-vVERSION`                                  | `release-csharp.yml`                                           | NuGet Trusted Publishing through the protected `nuget` environment                      |
| [Go](https://github.com/deancochran/ftms/blob/main/packages/go/docs/releasing.md)         | `packages/go/vVERSION`                             | No automatic publication workflow; `go-ci.yml` verifies source | Nested Go module tag, public proxy/checksum database and isolated consumer verification |

Run `pnpm release:prepare PORT --dry-run` first. It is deliberately read-only:
version/changelog updates can require package-specific lockfile or metadata changes,
so make them in a reviewed PR using the package runbook. It never tags, pushes,
publishes, or contacts credentials; Python readiness retains PEP 440 validation.

The [coordinated 1.0 milestone](https://deancochran.github.io/ftms/project/release-one-zero/index.md) tracks stable-interface reviews and
package-specific blockers. It is not a claim that 1.0 artifacts are available.
Before the first `typescript-v1.0.0` (or 1.0 prerelease) push, verify tag/ruleset
and environment restrictions protect and permit `typescript-v*`. An absent tag
rule or approval boundary is a release blocker, not implicit permission. The npm trusted-publisher
workflow filename remains `publish.yml`; no remote settings change is implied.

### Release entry naming

Future GitHub release titles use **`FTMS LANGUAGE VERSION`**, with the native version
and no extra `v` prefix. Generate the title from the current package metadata with
`node tools/release-title.mjs PORT` (read-only). For example: `FTMS Go 0.1.0`,
`FTMS C# 0.1.0-alpha.1`, or `FTMS Python 0.1.0a2`. Put the registry/package ID,
exact tag/commit, public-consumer result and artifact checksums in the body.
Only create a publication evidence entry after public verification succeeds.

Existing automated C, Swift, Kotlin and Rust release titles already follow this
format. Other publication workflows do not automatically create GitHub entries;
record those as a separate authorized release-completion step using the generated
title and verified evidence. A missing GitHub entry does not imply an unpublished
registry package. Do not backfill historical releases without their exact evidence.

Do not rename historical releases or regenerate their notes from current source:
immutable tagged retry tooling can compare titles and bodies exactly. Preserve
historical tags, assets and metadata. Source documentation updates never authorize
republishing the same version with changed README, changelog or classifier bytes.
See [naming and versioning conventions](https://deancochran.github.io/ftms/project/versioning/index.md#naming-conventions).

C# readiness validates canonical NuGet version identity, not public availability.
Its native verification remains credential-free. The tag-only release workflow
requires a signed annotated tag, main ancestry, all-host native checks and the
protected NuGet environment before publishing the exact tested artifacts.
See the [C# release runbook](https://github.com/deancochran/ftms/blob/main/packages/csharp/docs/releasing.md).
Public verification must compare the tested archive's payload with the downloaded
package and verify NuGet's repository signature: repository signing changes the
archive hash without changing its payload. Never accept an existing version solely
because a push reports a duplicate.

For a coordinated release, run `pnpm release:prepare all --dry-run`. It checks all
nine packages' version metadata and changelogs, emits each intended version/tag, preserves every
failure in a JSON report, and exits nonzero if any package fails. CI retains this
as `release-metadata-readiness`. To save machine-readable JSON locally, use
`node tools/release-prepare.mjs all --dry-run > release-readiness.json` outside the
tracked source tree (or redirect to your approved temporary evidence directory).
This is **metadata-only preflight**, not a simulation of publication or a check
that a version is still available. Existing versions may already be immutable.
Go has no manifest package-version field: preflight reads its first versioned
changelog heading and emits the required nested-module tag, not `go-vVERSION`.

Retries are permitted only for the exact tag commit and verified artifact identity.
The C/Swift GitHub helper creates an absent release, continues matching assets,
uploads missing assets, rejects unexpected/different assets or a different tag
commit, and downloads the resulting assets to verify their hashes. PyPI and npm
verify public artifact integrity before accepting an existing version. npm also
downloads the exact public archive and runs an isolated installed consumer after
publication or a matching retry, retaining `npm-release-evidence`. Dart checks an
existing version's exact extracted file manifest and hosted consumer rather than
attempting another upload. No retry may replace published bytes.

## Coordinated release checklist

A full release is a tracked set of independent package releases, **not an atomic
cross-registry transaction**. Do not force every ecosystem to use one version or
push all tags indiscriminately. Do not retag an already published version to the
cleanup commit. Use [the release matrix](https://deancochran.github.io/ftms/project/releases/index.md) as historical
evidence, then recheck live state before any authorized release.

1. Inventory all nine packages. For each, record the package version, intended
   tag, exact reviewed commit, target registry, and whether this is a new release
   or verification of an existing one. Select new versions from actual package
   changes; update each changelog, lockfile and package-specific metadata in the PR.
2. Run all-package metadata preflight and `pnpm site:verify`. Require the full CI
   matrix on the final reviewed commit (manual `CI` dispatch selects every port).
   Inspect compiler, corpus and isolated installation evidence from each package;
   `pnpm verify` covers TypeScript, not native ports. Missing/skipped required
   evidence is a blocker, not a pass.
3. Confirm registry ownership, protected tags, required checks, trusted publishers
   and environment reviewers with an administrator. Dart's first manual pub.dev
   upload and publisher setup are recorded in the release matrix; verify that the
   protected publisher remains configured before subsequent releases.
   Source scaffolds or future ports are not release targets.
4. After explicit integration and publication authorization, tag the exact
   reviewed `main` commit using each package's namespace. Push individual approved
   tags only. Follow the package runbook and inspect the tag workflow's identity
   gate before approving publication. A local tag is not proof of a pushed tag,
   registry upload or successful consumer.
5. Track every package independently through **prepared → verified → published →
   public-verified**. Record tag/commit, workflow run/attempt URL, archive hashes,
   corpus/contract hashes, installation reports and any failures. Do not call the
   coordinated release complete until every intended package is public-verified
   (or an explicit scope change is approved).
6. Update `docs/released-packages.md`, versioning/support summaries, package guides
   and site landing copy only from verified publication evidence. Build the site
   again; approved Pages deployment is separate from registry publication.

## Refresh public installation guidance

After public artifacts and fresh installed consumers pass, update
`docs/published-installations.json` with the verified version, evidence anchor,
and C checksum or Swift full revision as applicable. Do not copy candidate
manifest versions into this record. Retain historical evidence in the release
ledger, update its current table, and run `pnpm docs:install:generate`.
The generated `docs/install.md` is committed Markdown for both GitHub and the site.
Keep matching Kotlin/Swift README snippets synchronized; `pnpm docs:check` detects drift.
Update current quickstart pins/lockfiles in the same reviewed release-follow-up
change and rerun their installed-consumer tests. Leave historical fixtures pinned.
Generation is offline: it neither discovers registry versions nor proves publication.

## Failure triage and recovery

| Failure stage                                     | What to inspect                                                                | Safe next action                                                                                                               |
| ------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Metadata or tag identity                          | Version/changelog, tag's resolved commit, clean state, main ancestry           | Fix untagged source in a reviewed PR. Never move a public tag.                                                                 |
| Compiler, conformance, docs or installation       | Failing job and retained reports; exact source/corpus hashes; skipped cases    | Fix the candidate and rerun required verification before publication.                                                          |
| Authentication or approval                        | Environment, tag restrictions, OIDC binding, registry ownership                | Have an authorized administrator repair settings; do not substitute a long-lived token or bypass approval.                     |
| Upload timeout or partial upload                  | Exact registry version and public artifact hashes, not just the job conclusion | Treat publication state as unknown until checked. Resume only under the package's matching-artifact retry rules.               |
| Public integrity or consumer failure after upload | Downloaded bytes, expected manifest, public verification report                | Mark **published, verification failed**. Do not claim rollback or overwrite. Investigate; changed bytes require a new version. |
| Docs deployment only                              | `Documentation site` build/deploy and Pages settings                           | Correct/redeploy docs with approval; do not republish unchanged packages.                                                      |

Keep a failure record with package/version/tag/commit, failed stage, run URL,
expected/actual public identity and recovery decision. Retain artifact reports
before CI retention expires; redact credentials and private logs. Re-running a
publishing workflow can mutate remote state even when an existing version is
expected, and requires explicit authorization. Partial success in one registry
does not authorize continuing the other releases blindly.

Administrators separately roll out protected tags, required-check migration, OIDC environments/trusted publishers, and registry authorization. Workflow code cannot establish remote settings. The `main` documentation site is current-source documentation, not an automatically versioned latest release. Swift remains consumed by immutable Git revision, and C Conan/vcpkg submissions remain separate.

## CI and settings rollout

`CI` is the PR/main entry point. Its `CI summary` check requires all selected
port checks, workflow/helper tests and documentation checks to finish successfully.
Package changes select that port and docs; shared contracts, workflow/tooling and
unknown root changes conservatively select every port. Docs-only changes select
docs. Manual CI runs select everything. Language workflows remain manually runnable
and reusable by release gates; they no longer duplicate PR/main runs.

Before relying on selective checks, update branch protection/rulesets to require
`CI summary` instead of the former individual language or docs job checks. Confirm
the exact displayed check name on an approved PR. Do not leave old required checks
configured: intentionally skipped or renamed checks can block merging.

Keep npm's trusted publisher bound to `publish.yml`, PyPI's to
`release-python.yml` and environment `pypi`, and the existing package environments
and credentials for Maven Central/crates.io. Confirm protected release tags and
the Dart `pub-dev` environment/trusted publisher after its first manual publication.
Confirm environment restrictions separately. No settings changes are performed by these
scripts. Pages retains `PAGES_ENABLED=true` and the `github-pages` environment;
merging to `main` automatically builds and deploys the site when Pages is enabled.
Manual `Documentation site` dispatch on main can rebuild/redeploy it independently.

The readiness command validates metadata only, not compiler/conformance evidence,
registry configuration, branch ancestry or authorization to publish. Follow each
package's runbook for those checks. Re-running a tag workflow is a remote action
and must be explicitly authorized even when the intended result is verification.
