Skip to content

docs: 0.x.y indefinitely; parity is behavioural, not a version number - #66

Merged
scttfrdmn merged 1 commit into
mainfrom
docs/versioning-policy
Aug 1, 2026
Merged

docs: 0.x.y indefinitely; parity is behavioural, not a version number#66
scttfrdmn merged 1 commit into
mainfrom
docs/versioning-policy

Conversation

@scttfrdmn

@scttfrdmn scttfrdmn commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Two policy decisions, written down where they'll be read. Neither was recorded anywhere, and both were about to be violated.

1. 0.x.y indefinitely

There is no planned 1.0.0, so a MINOR bump is the breaking-change signal for the life of the project — not a pre-release convention. The old CHANGELOG line ("Pre-1.0, breaking changes bump the MINOR version") implied a 1.0 was coming and that the rule would expire with it. Both halves were wrong.

2. The version line is spawn-ts's own, not Go spawn's

0.6.1 here against v0.97.0 there. Matching those numbers would assert a feature correspondence that doesn't exist — and it would be the wrong thing to fix, because most of the gap isn't a gap. Roughly 22,700 lines of Go pkg/ plus all 11,385 of lambda/ are the daemon/server/provisioning half of the architecture: the half spawn-ts writes spawn:* tags for rather than reimplements in a browser tab.

So parity is a behavioural claim carrying documented divergences, audited per-command across five tiers in #57 — never a claim that two version strings agree. The README now points at the two live examples and states the rule they follow:

A divergence that isn't written down is a bug; one that is, is a design decision.

Those examples are the Elastic IP lookup (api.md — Go's GetInstanceElasticIP returns nil, nil on any API error, making a missing permission indistinguishable from a clean bill of health) and refusing an unhonourable plugin before launch (data-movement.md — Go parks it at StatusWaitingForPush on the box instead).

The concrete contradiction

The milestone. v1.0.0 — Feature parity named a version that will never ship, so it's renamed v0.7.0 — Go parity (documented divergences) — 2 open / 7 closed, membership unchanged. #57's body opened by quoting the old name, so it's updated to match.

CONTRIBUTING.md gains a Versioning section: spawn-ts was the only one of the four -ts repos that said nothing about versioning at all, and it's the repo where the 1.0 expectation had taken root.

Companion PRs

Same policy, per-repo wording: truffle-ts#45, lagotto-ts#9, advisor-ts#5. advisor-ts's differs on purpose — it has no Go original, so it makes no parity claim, and saying so keeps a reader from inferring a missing audit where there's nothing to audit against.

Verification

Docs only; no source change. npm run typecheck clean, 538 tests pass. Every version number cited checks out against package.json and the actual Go releases (gh release list), and both README doc anchors resolve to real headings — a broken anchor would undercut the "checkable" claim the paragraph makes.

Two pre-1.0 mentions survive in truffle-ts/lagotto-ts, both inside already-shipped release entries. Those are the historical record of what was published and aren't rewritten.

Two policy decisions written down where they'll actually be read, because
neither was recorded anywhere and both were about to be violated.

1. spawn-ts stays on 0.x.y indefinitely. There is no planned 1.0.0, so a
   MINOR bump is the breaking-change signal for the life of the project,
   not a pre-release convention. The CHANGELOG's "Pre-1.0, breaking
   changes bump the MINOR version" implied a 1.0 was coming and that the
   rule would expire with it; both halves were wrong.

2. spawn-ts's version line is its own, and deliberately NOT Go spawn's:
   0.6.1 here against v0.97.0 there. Matching them would assert a feature
   correspondence that doesn't exist — and it would be the wrong thing to
   fix, because most of the gap isn't a gap. ~22,700 lines of Go pkg/ plus
   all 11,385 of lambda/ are the daemon/server/provisioning half of the
   architecture: the half spawn-ts writes spawn:* tags FOR rather than
   reimplements in a browser tab.

   So parity is a behavioural claim carrying documented divergences,
   audited per-command across five tiers in #57 — never a claim that two
   version strings agree. The README now points at the two live examples
   (the Elastic IP lookup in api.md, refusing an unhonourable plugin
   before launch in data-movement.md) and states the rule they follow: a
   divergence that isn't written down is a bug; one that is, is a design
   decision.

The milestone was the concrete contradiction. `v1.0.0 — Feature parity`
named a version that will never ship, so it's renamed to `v0.7.0 — Go
parity (documented divergences)` (2 open / 7 closed, membership
unchanged), and #57's body is updated to match — it opened by quoting the
old name. CONTRIBUTING gains a Versioning section, since spawn-ts was the
only one of the four -ts repos that said nothing about versioning at all,
and it's the repo where the 1.0 expectation had taken root.

Docs only; no source change. Verified: typecheck clean, 538 tests pass,
every version number cited checks out against package.json and the actual
Go releases, and both README doc anchors resolve to real headings.
@scttfrdmn
scttfrdmn merged commit 30c5ebc into main Aug 1, 2026
1 check passed
@scttfrdmn
scttfrdmn deleted the docs/versioning-policy branch August 1, 2026 15:54
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