Skip to content

feat!: staging SDK builds are X.Y.Z-rc.N in every ecosystem - #21

Merged
battuashwik merged 7 commits into
mainfrom
feat/rc-staging-suffix
Oct 10, 2026
Merged

battuashwik merged 7 commits into
mainfrom
feat/rc-staging-suffix

Conversation

@battuashwik

Copy link
Copy Markdown
Member

Renames the SDK staging prerelease from -staging.N to -rc.N in every ecosystem. The channel is still called staging; only the version spelling changes. Plan: fireweaveai-platform/.aidocs/2026-10-09-1240-sdk-staging-to-rc-plan.md (rev 4).

Why

Maven sorts an unknown qualifier like -staging after the release, so 3.0.0-staging.1 outranks 3.0.0. rc sorts before the release in npm, Go, Swift, Rust, Dart, PEP 440 and Maven/Gradle.

What changes

  • Runtime rule (SP-13): from 3.0.0, a build is staging only when its version contains -rc.. Python keeps "any PEP 440 pre-release or dev release is staging". -staging.N is no longer a staging spelling. This is a breaking change.
  • Release tooling: staging cuts are X.Y.Z-rc.N. Python is X.Y.ZrcN on PyPI, and Java X.Y.Z-rc.N goes to Maven Central. Any other staging spelling is refused, and version.sh check-stamp checks the stamped channel before every publish.
    • Swift is left out of all and refused on staging until the mirror exists.
    • The tag-push publish paths in publish-java.yml and publish-python.yml are retired.
  • Rust: the staging counter reads tags, and nothing staging goes to crates.io.
  • Changelog: starts from the last plain release or rc, never a legacy staging tag.
  • Tags: Rust, Dart and Swift tags point at a release commit that carries the applied version. The v3.0.0-staging.1 tags point at an unstamped main, so those Rust and Dart builds call production.
  • Docs: SP-13, the ADR-0012 amendment, RELEASE.md, the CHANGELOG and the READMEs.

Checked locally

  • tools/release/version.test.sh: 151 passed, 0 failed.
  • compare-start.mjs: 14 fixtures, 110 cases, 0 schema problems.
  • Node 214 + 14 pass; web, Go and Python pass.
  • Not run here: Swift (no toolchain), Java, Rust and Dart. Their results are in this PR's CI.

Before the first rc cut

Merge fireweaveai-platform's matching changes first; they're on its feature/integration-refactor branch. The owner steps (delete the orphan java/ and swift/v3.0.0-staging.1 tags, add the tag ruleset, confirm Maven deployment 922e7f2c, then npm deprecate the staging.1 versions) are in the plan's release-ordering section.

… no longer a staging spelling

The channel rule in Go, Java, Rust, Swift and Dart (channelForVersion)
now treats a version containing "-rc." as staging and everything else,
including -staging.N, -beta.N, -rc without an iteration, build metadata
and pseudo-versions of a release or of the legacy v3.0.0-staging.1 tag,
as production. Python keeps its PEP 440 rule (any pre-release or dev
release is staging); the release tooling emits only X.Y.ZrcN.

start-channel-rule gains the rc, legacy-staging, beta, no-iteration,
build-metadata, Go pseudo-version and dev-store cases; the pep440 fixture
makes rcN its primary case and adds the unnormalised -rc.N spelling
(start suite: 14 fixtures, 110 cases). Node/web build-info tests read
the stamp against -rc. instead of -staging.N.

BREAKING CHANGE: a -staging.N version no longer selects the staging
fw-server in the rule-based SDKs.

Signed-off-by: Ashwik Battu <battuashwik@gmail.com>
…Java on Central), refuse any other spelling, and check the stamped channel before publishing

version.sh compute emits X.Y.Z-rc.N (Python X.Y.ZrcN) on channel=staging,
counting N from -rc.N / rcN only, so legacy -staging.N and aN versions
never feed the counter and the first rc of a base is N=1. The Python
counter reads pypi.org on both channels. A staging version without the rc
spelling is refused (exit 4). The server/web/dart/swift stamps call
staging only for *-rc.*.

A new check-stamp subcommand reads the channel the stamped workspace will
call (the stamp file, or the manifest version through the runtime rule for
rust/java/python, or the tag version for go) and fails unless it equals
the dispatched channel. release.yml runs it after every apply, plus the
node/web/dart build-info test on the stamped tree.

release.yml: `all` drops swift and a staging component=swift is refused in
validate; publish-pypi uploads the rc to PyPI on environment release with
PYPI_API_TOKEN; publish-maven requires -rc. on staging; the tag job runs on
the channel's environment. publish-java.yml and publish-python.yml lose
their tag-push triggers and accept only a dispatched plain version.

Signed-off-by: Ashwik Battu <battuashwik@gmail.com>
…r receives a staging upload

Signed-off-by: Ashwik Battu <battuashwik@gmail.com>
…ever from a legacy staging tag

changelog.sh took the highest tag of any spelling. v3.0.0-staging.1 sorts
above every -rc.N and above 3.0.0, so every 3.0.0 changelog would have
started "since staging.1", and a python 3.0.0 changelog would have started
from its own rc.

The previous tag now depends on the channel, read from the version's
spelling (an rc, X.Y.Z-rc.N or python X.Y.ZrcN, is a staging run):
production starts from the highest plain X.Y.Z tag; staging from the
higher of that and the highest rc tag, where a release beats its own rc.
Pre-rename -staging.N and aN tags never count. A version-sorted filter is
used rather than git describe, so a tag on a detached release commit is
still found.

changelog.test.sh builds a scratch repo with plain, legacy staging, rc and
detached rc tags and pins the previous tag for production and staging runs
of server and python; ci.yml runs it beside version.test.sh.

Signed-off-by: Ashwik Battu <battuashwik@gmail.com>
…ng from 3.0.0

Signed-off-by: Ashwik Battu <battuashwik@gmail.com>
…rying the applied version

Signed-off-by: Ashwik Battu <battuashwik@gmail.com>
… staging is not pinned

crates.io and pub.dev never receive an rc, so the Rust and Dart READMEs show
the git-tag install for a staging build and say it is the one install that
records an exact build (re-run with a higher tag to move). RELEASE.md no
longer tells npm staging users to pin the version @next resolves.
@battuashwik
battuashwik merged commit 1434bc9 into main Oct 10, 2026
25 of 29 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant