The version in the text is not the one in the code
version-mismatchon by defaultJapanese / English
A version named right above a code block that the block does not use
Example
How to fix
Check which of the text and the code has the current version, and correct the other.
Why it matters
When "Install version 2.3.0" sits right above a command that installs tidyq@2.4.0, the reader cannot tell which to install. It happens when a release updates the example or the text but not both. chaff compares a version written in the paragraph right above a code block (a number in three dotted parts, such as 2.3.0) with the version the block shows. It reports when the block shows exactly one version and the paragraph names another. When the block pins a program by name (redis:7.4) and the paragraph writes a version right after that name (Redis 7.2), versions of two parts are compared too; 7.4 and 7.4.1 are the same series. In a document that lists its releases (version headings, as in a changelog, or list items that start with a version), a command that installs the document's own package (the one its title or opening paragraph names) pinned to one version, such as npm install wrapkit@3.1.0, is compared with the release whose section it is in, or else with the newest release listed.
What it does not flag
A code block with no version or with two or more (an upgrade from one to the other), a version written as a bound or a starting point ("from 2.3.0", "20.0.0 or later"), a version right after the name of another program ("Requires Node.js 18.17.0"), a version in a heading, a list item, a table or a line of its own, numbers in two parts (22.04, 3.1) other than right after the name of a program the block pins, and numbers with a four-digit first part (2024.01.15) are not compared. Of install commands, a package the title or the opening paragraph does not name (a dependency), a range (^3.0.0, >=3.0.0), a tag such as latest, a prerelease (4.0.0-beta.1), and a document that lists no releases are not compared; the newest release is chosen by version order, prereleases left out.
Turning it off or relaxing it
Technical details
- Layer
- L1
- Status
- stable
- Severity
- warning
- Languages
- Japanese and English
- Suited to
- technical, docs, blog, legal, academic, literature, speech
- Reads from the document
- markdown
Levels
Set a level for this rule under rules in chaff.yaml. With nothing set, it runs at the level its genre gives it (see By genre below).
| strict | error |
|---|---|
| normal | warning |
| relaxed | info |
This rule has no limit to count to. A level sets how a finding is marked: relaxed keeps the finding and marks it a step lower.
By genre
- Runs by default in
- technical/spec, technical/readme, blog/tech, blog/essay, blog/owned-media, docs/manual, docs/faq, docs/glossary
- Turned off by the genre in
- legal/contract, legal/statute, legal/judgment, legal/patent, academic/paper, literature/fiction, literature/essay, literature/poetry, literature/play, speech/address, speech/transcript
- Not suited to, and not run in
- business/proposal, business/report, business/email, business/press-release, business/meeting-notes
Message
"{written}" is written, but the code below has {code}
This command installs {pinned}, but the newest release this document lists is {release}
This command installs {pinned}, but it is written under the release {release}
This page is built from the rule's definition file:packages/chaff/rules/version-mismatch.yaml