Skip to content

docs: stop the README from naming which release is current - #61

Merged
kkdev92 merged 1 commit into
mainfrom
docs/stop-version-drift
Sep 2, 2026
Merged

docs: stop the README from naming which release is current#61
kkdev92 merged 1 commit into
mainfrom
docs/stop-version-drift

Conversation

@kkdev92

@kkdev92 kkdev92 commented Sep 2, 2026

Copy link
Copy Markdown
Owner

Removes the two sentences that said which version was current, and pins the
versions that remain with a test.

Why

Both sentences were wrong within a day of being written:

  • `4.1.0` is the current release
  • `4.1.0` is the current release and holds `latest` on npm

4.1.1 shipped and neither moved. The npm badge at the top of the README already
renders the current version, and it is generated — so the prose was duplicating
a fact it had no way to keep.

An earlier change rewrote these to name the line (4.1, 4.x) instead of the
patch. That only lengthens the interval: 4.1 goes stale at 4.2 and 4.x at
5.0. The sentences are gone instead. What is left says what does not move — that
2.x continues on v2-maintenance, and that the CHANGELOG is where per-release
detail lives.

The versions that stay are requirements, so they are pinned

A reader deciding whether to adopt does need the floors. Those stay, and a new
suite holds them to the manifest:

  • the VS Code and Node floors quoted in the documentation are the strings
    engines declares
  • no other VS Code version is named on any documented page
  • @types/vscode has not drifted away from engines.vscode — the README says
    the two move together, and this is that sentence as a check
  • no page claims to know which release is current

This follows what tests/readme-samples.test.ts already does for documented
code: the same argument, applied to the documented numbers.

Verification

Each assertion was checked by breaking what it guards and confirming it fails —
a test that only ever passes proves nothing:

Change made Caught by
README's VS Code floor set to 1.133.0 floor match, and "no other version named"
README's Node floor set to >=20.0.0 Node floor match
A stray 1.125.0 added to the README "no other version named"
@types/vscode set to ~1.120.0 types-track-the-floor
The previous README restored "leave currency to the badge", naming both sentences

Full suite: 1087 tests in 73 files. No package content changes beyond the
README.

🤖 Generated with Claude Code

Two sentences said which version was current, and both were wrong within a day
of being written -- `4.1.0 is the current release` survived into 4.1.1. The npm
badge at the top already renders the current version and is generated, so the
prose was duplicating a fact it could not keep.

Naming the line instead of the patch, as an earlier change did, only lengthens
the interval: `4.1` goes stale at 4.2 and `4.x` at 5.0. Both sentences are gone
instead, and the surrounding text says what does not move -- that 2.x continues
on `v2-maintenance`, and that the CHANGELOG is where per-release detail lives.

The versions that remain are requirements, which a reader does need, so they are
pinned rather than removed: a new suite checks that the floors quoted in the
documentation are the strings the manifest declares, that no other VS Code
version is named anywhere, that `@types/vscode` has not drifted away from
`engines.vscode`, and that no page claims to know which release is current.

Verified against the text this replaces: restoring the previous README fails the
last of those with both sentences named. The full suite is 1087 tests in 73
files.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Tfbt5Vy1jB9C6mMAHXhLY
@kkdev92
kkdev92 merged commit 6720273 into main Sep 2, 2026
10 checks passed
@kkdev92
kkdev92 deleted the docs/stop-version-drift branch September 2, 2026 11:45
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