SPOKE Protocol

English

简体中文

English

简体中文

Appearance

Version & release ​

SPOKE publishes a single lockstep SemVer across all workspace packages and Rust consumer crates, so integrators pin one version across TypeScript and Rust artifacts. Releases are annotated git tags vX.Y.Z, materialized as GitHub Releases, and published to npm and crates.io on every tag without a -rc. prerelease segment.

What to pin ​

  • npm — @42ch/spoke-schemas, @42ch/spoke-operations
  • crates.io — spoke-schemas, spoke-operations
  • Same X.Y.Z everywhere; tags vX.Y.Z match the lockstep version.

Release shape ​

  • Lockstep manifests — workspace root, both TS packages, both Rust crates, fixture/codegen tooling, and Cargo.lock all share one version; CI asserts zero drift (pnpm run verify:version).
  • Tags — annotated vX.Y.Z. Every tag without -rc. — stable vX.Y.Z or prerelease like v0.1.0-alpha.3 — publishes to npm and crates.io; tags with -rc. (vX.Y.Z-rc.N) create GitHub pre-releases only.
  • Notes — release notes come from CHANGELOG.md, generated by git-cliff from Conventional Commits.
  • Publish — npm and crates.io via CI Trusted Publishing on every tag without -rc.; -rc. tags create GitHub pre-releases only.

SemVer semantics ​

  • PATCH — bugfix-only packaging release; the wire contract stays unchanged.
  • MINOR — backward-compatible wire or ops library additions.
  • MAJOR — breaking wire or public API change (pre-1.0, allowed without a deprecation period).

Pin methods ​

  • npm: pnpm add @42ch/[email protected] @42ch/[email protected]
  • crates.io: spoke-schemas = "X.Y.Z", spoke-operations = "X.Y.Z"
  • Git tag: git checkout vX.Y.Z; or a GitHub Release source archive for that tag.

Package SemVer vs wire schema_version ​

Package SemVer and the integer wire schema_version move independently — a bump to one does not require a bump to the other. As an exception, release notes explicitly couple the two when a release covers both a package bump and a wire change.

More resources ​