docs: say alpha, not pre-release, across landing page and READMEs - #571
Merged
Conversation
xNet is no longer pre-release: the @xnetjs/* packages are published on npm, the desktop app is downloadable, and the hub image ships. But it is still early — APIs, schemas and wire formats change between releases. The site and READMEs said "pre-release", which understates what has shipped and overstates how settled it is. - Hero badge: "Pre-release — built in the open" -> "Alpha — shipping, and still moving fast" - Community section, compare page copy and both compare footnotes reworded - xNet's three compare rows: maturity 'pre-release' -> 'alpha' (Habitat's row is untouched — that is a third party's own status) - Root README: an up-front alpha callout, including the note that package version numbers are not a maturity signal (core is already past 2.x) - Download page: an alpha banner above the platform cards, pointing at .xnetpack export for backups - Docs introduction: a matching caution callout - All 18 publishable package READMEs: a short alpha banner after the intro, so the notice shows on the npm package page Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: xNet Test <test@xnet.dev>
Contributor
|
✓ Changelog fragment found — thanks! |
Contributor
🖼️ UI changes in this PRScreens✏️ Discover _(SSIM 0.982)_
Auto-captured by CI · run. Informational — not a blocking check. |
Contributor
|
Preview removed for PR #571. |
crs48
added a commit
that referenced
this pull request
Jul 19, 2026
Follow-up to #571. That PR swept the landing page, all 18 package READMEs, the compare page and the docs introduction — but a final grep turned up one straggler: the cryptography concept page still opened with "Since xNet is prerelease software". The underlying point is unchanged and still true — being early is exactly *why* hybrid post-quantum crypto can ship as a clean implementation with no migration debt. Only the label was wrong: > Since xNet is prerelease software, hybrid security ships as a clean implementation > **Because xNet is still alpha,** hybrid security ships as a clean implementation `llms-full.txt` regenerated to match. ## What I deliberately left alone - `Maturity` type still includes `'pre-release'` — Habitat's compare row legitimately uses it; that's a third party's own status - `xnet-prerelease` / `fw-xnet-prerelease` footnote **ids** — identifiers, not copy, per the repo's identifier-vs-copy rule - The 2026-06-23 changelog entry mentioning "pre-release resets" — a dated historical record, not a current claim ## Verification `pnpm --filter ./site build` passes — 42 static pages, all validators green. Site-only, no publishable package touched, so no changeset. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
crs48
added a commit
that referenced
this pull request
Jul 19, 2026
…585) Follow-on from #571 / #583, which made every human-readable surface say "alpha" while `@xnetjs/core` still says `2.5.0`. ## The short version **The renumber isn't available, and the number was never the problem.** - npm never lets a version string be reused, and since **npm 11** (which we pin in `npm-release.yml:40`) publish refuses to move `latest` backwards. `@xnetjs/core@0.5.0` is publishable as a string but incoherent as a release. - The unpublish escape needs **<300 downloads/week**; core pulls **2,120**. Door shut regardless of whether that traffic is real users or bots. - A true 0.x requires a **scope rename** — `@xnet/core` returns 404, so it looks free. Costed as a real option rather than dismissed, since nobody's meaningfully depending on us yet. - Worth knowing: under node-semver `^0.2.3` and `~0.2.3` are **identical**. 0.x buys safety through total friction, not signalling. ## Four enforcement gaps, all verified against the code | Gap | Evidence | |---|---| | Stop hook checks a changeset **exists**, never that the bump matches the diff | `assert-coverage.mjs:95-105` — regex for `name: patch\|minor\|major` | | `schema-check.yml` is a **stub that can never fail** | `:33,:41` placeholder `{"schemas":[]}` both sides; `:49` zeroed fallback | | ~25 protocol constants hand-maintained, **one already drifted** | TS `CURRENT_PROTOCOL_VERSION = 4` vs Swift `protocolVersion: Int64 = 3` | | Ignored packages ship wire-visible changes with no release intent | `hub` (Docker image), `editor` (`content-v4`) both in `.changeset` `ignore` | The Swift drift is a live correctness bug, not just hygiene — it's the enforcement gap made visible. Also relevant: **JS has no tool that detects a breaking change.** `cargo-semver-checks` has no equivalent; semver-ts.org's own tooling appendix recommends hand-written assertions. That's why `CLAUDE.md`'s "bump from the diff" is a *human* instruction. ## Recommendation Keep the numbers. Write `STABILITY.md`. Scope semver to a surface we can actually hold via api-extractor release tags (`@public`/`@beta`/`@alpha`/`@internal`) — **a smaller honest promise beats a bigger dishonest one**. Fix the drift, delete or implement the stub. Then decide the rename separately, because a rename without gates lands us back at `@xnet/2.5.0` in a year. ## Verification - All 15 cited repo paths confirmed to exist - All 4 mermaid diagrams parse (validated against the site's mermaid build) - Registry facts pulled live from npm, not recalled Two things flagged as unproven in the doc: whether the `@xnet` scope is genuinely claimable (an unpublished-but-reserved scope looks identical from outside), and what the 2,120/week download traffic actually is. Docs only — no changeset needed. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
xNet isn't pre-release any more —
@xnetjs/*is on npm, the desktop app is downloadable, and the hub image ships. But it's still early, and the site said "pre-release" in a way that both undersells what's shipped and oversells how settled it is.This makes the actual state explicit in more places: released, but alpha.
What changed
Landing page
Pre-release — built in the open→Alpha — shipping, and still moving fastCompare page
maturity: 'pre-release'→'alpha'. Habitat's row is left alone — that's a third party's own status, not ours.Download page
.xnetpackexport for their own backupsREADMEs
README.md: an up-front callout, including the bit that's easy to miss — package version numbers are not a maturity signal (core is already past 2.x, and lockstep versioning means that number says nothing about stage)Docs
introduction.mdxgets a matching:::cautioncallout (andllms-full.txtregenerated to match)Verification
pnpm --filter ./site buildpasses — 124 pages, all site validators green (validate:comparecovers the maturity changes)/,/download,/compare,/docs/introduction/in light and darkDownload page, dark mode
The banner uses the same amber tone as the existing
MaturityBadgealpha/beta styling.Note
The
.changesetis a patch across all 18 packages. README text ships inside the npm tarball, so this is consumer-visible — but there are no code changes in this PR.🤖 Generated with Claude Code