[GH-ISSUE #609] Applying Semantic Versioning to documentation #6420

New Issue

GiteaMirror · 2026-06-17T05:12:11-05:00

GiteaMirror commented

2026-06-17 05:12:11 -05:00

Originally created by @epement-db on GitHub (Sep 2, 2020).
Original GitHub issue: https://github.com/semver/semver/issues/609

Should semver include provisions for normal documents or text files? A suggestion:

For documentation not tied to a versioned software item, changes that add, delete, or move main headings (1, 2, 3, ...) should increment the Major version number. Changes to add, delete, or move subheadings (1.1, 1.2, ...) should increment the Minor version number, and changes only to body text are equivalent to Patch version changes.

Documentation for software releases should have the version number of the document correspond to the software version it describes. To indicate textual revisions or corrections, append lower-case letters to the last digit. Thus, "3.1.5" (first version), "3.1.5a", "3.1.5b", etc.

Originally created by @epement-db on GitHub (Sep 2, 2020). Original GitHub issue: https://github.com/semver/semver/issues/609 Should semver include provisions for normal documents or text files? A suggestion: For documentation not tied to a versioned software item, changes that add, delete, or move main headings (1, 2, 3, ...) should increment the Major version number. Changes to add, delete, or move subheadings (1.1, 1.2, ...) should increment the Minor version number, and changes only to body text are equivalent to Patch version changes. Documentation for software releases should have the version number of the document correspond to the software version it describes. To indicate textual revisions or corrections, append lower-case letters to the last digit. Thus, "3.1.5" (first version), "3.1.5a", "3.1.5b", etc.

GiteaMirror added the question label 2026-06-17 05:12:11 -05:00

GiteaMirror commented

2026-06-17 05:12:12 -05:00

@ljharb commented on GitHub (Sep 3, 2020):

I suppose you could, but why? Cool URLs don't change, so links (including heading anchors) should never disappear anyways, and what does it mean to have a "breaking" change to a doc?

@ljharb commented on GitHub (Sep 3, 2020): I suppose you could, but why? Cool URLs don't change, so links (including heading anchors) should *never* disappear anyways, and what does it mean to have a "breaking" change to a doc?

GiteaMirror commented

2026-06-17 05:12:13 -05:00

@Nixinova commented on GitHub (Jan 12, 2021):

SemVer's domain is "APIs", but you could include "incoming links" to that category. In that case I would consider any change that usurps the URL or breaks section headings to be major, expansion of the page with new sections to be minor, and smaller updates or typo fixes/copyedits/etc to be patch.

@Nixinova commented on GitHub (Jan 12, 2021): SemVer's domain is "APIs", but you could include "incoming links" to that category. In that case I would consider any change that usurps the URL or breaks section headings to be major, expansion of the page with new sections to be minor, and smaller updates or typo fixes/copyedits/etc to be patch.

GiteaMirror commented

2026-06-17 05:12:14 -05:00

@Nixinova commented on GitHub (Jan 12, 2021):

Appending letters to the version is out of SemVer's scope.

@Nixinova commented on GitHub (Jan 12, 2021): Appending letters to the version is out of SemVer's scope.

GiteaMirror commented

2026-06-17 05:12:14 -05:00

@ghost commented on GitHub (Feb 15, 2021):

Documentation should be updated along with the code. That being said, there are times when documentation needs to be expanded upon or maintained (e.g., due to user feedback, new discoveries, etc.).

The problem I see with SemVer in regards to documentation updates is that the specification requires a fully-documented API, but doesn't specify how standalone documentation updates should be reflected in the version number. There are cases where a user's experience will drastically change just because of improved documentation.

If the philosophy of "software should just work" is assumed, then I would argue that doesn't account for complex pieces of software.

The existing SemVer structure can be leveraged, but I don't think it's necessary for a standalone documentation change to warrant a major or minor, or even a patch, increment. Build metadata is a perfect candidate for standalone documentation changes (e.g., 1.0.0-1d, 1.0.0-1doc, or 1.0.0-1nb standing for non-breaking).

@ghost commented on GitHub (Feb 15, 2021): Documentation should be updated along with the code. That being said, there are times when documentation needs to be expanded upon or maintained (e.g., due to user feedback, new discoveries, etc.). The problem I see with SemVer in regards to documentation updates is that the specification requires a fully-documented API, but doesn't specify how standalone documentation updates should be reflected in the version number. There are cases where a user's experience will drastically change just because of improved documentation. If the philosophy of "software should just work" is assumed, then I would argue that doesn't account for complex pieces of software. The existing SemVer structure can be leveraged, but I don't think it's necessary for a standalone documentation change to warrant a major or minor, or even a patch, increment. Build metadata is a perfect candidate for standalone documentation changes (e.g., 1.0.0-1d, 1.0.0-1doc, or 1.0.0-1nb standing for non-breaking).

GiteaMirror commented

2026-06-17 05:12:16 -05:00

@ljharb commented on GitHub (Feb 15, 2021):

Documentation-only updates are obviously patch - they don't break anything and they aren't adding a new runtime feature.

You can use a prerelease identifier, sure, but then semver ranges in ecosystems like npm aren't likely to automatically update to them.

@ljharb commented on GitHub (Feb 15, 2021): Documentation-only updates are obviously patch - they don't break anything and they aren't adding a new runtime feature. You can use a prerelease identifier, sure, but then semver ranges in ecosystems like npm aren't likely to automatically update to them.

GiteaMirror commented

2026-06-17 05:12:17 -05:00

@Nixinova commented on GitHub (Feb 16, 2021):

how standalone documentation updates should be reflected in the version number.

Answered by ...

Build metadata is a perfect candidate for standalone documentation

Yes but not how you used it: 1.0.0, 1.0.0+doc.1, 1.0.0+doc.2, etc.

@Nixinova commented on GitHub (Feb 16, 2021): > how standalone documentation updates should be reflected in the version number. Answered by ... > Build metadata is a perfect candidate for standalone documentation Yes but not how you used it: 1.0.0, 1.0.0+doc.1, 1.0.0+doc.2, etc.

GiteaMirror commented

2026-06-17 05:12:17 -05:00

@ghost commented on GitHub (Feb 16, 2021):

Documentation-only updates are obviously patch - they don't break anything and they aren't adding a new runtime feature.

That's not so obvious from reading the SemVer specification for patching:

Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.

@ghost commented on GitHub (Feb 16, 2021): > Documentation-only updates are obviously patch - they don't break anything and they aren't adding a new runtime feature. That's not so obvious from reading the SemVer specification for patching: > Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior.

GiteaMirror commented

2026-06-17 05:12:18 -05:00

@ljharb commented on GitHub (Feb 16, 2021):

That says when it must be incremented - not when it must not be. There’s nothing left to increment besides patch for docs-only changes, which aren’t part of the api at all.

if it’s ergonomic in your ecosystem to use build metadata or prereleases for docs, do so, but in the npm ecosystem it’s not, so patch is appropriate.

@ljharb commented on GitHub (Feb 16, 2021): That says when it must be incremented - not when it must not be. There’s nothing left to increment besides patch for docs-only changes, which aren’t part of the api at all. if it’s ergonomic in your ecosystem to use build metadata or prereleases for docs, do so, but in the npm ecosystem it’s not, so patch is appropriate.

GiteaMirror commented

2026-06-17 05:12:19 -05:00

@DivyabharathiMurugesan commented on GitHub (Jun 29, 2021):

Should semver include provisions for normal documents or text files? A suggestion:

For documentation not tied to a versioned software item, changes that add, delete, or move main headings (1, 2, 3, ...) should increment the Major version number. Changes to add, delete, or move subheadings (1.1, 1.2, ...) should increment the Minor version number, and changes only to body text are equivalent to Patch version changes.

Documentation for software releases should have the version number of the document correspond to the software version it describes. To indicate textual revisions or corrections, append lower-case letters to the last digit. Thus, "3.1.5" (first version), "3.1.5a", "3.1.5b", etc.

Hi,

Please refer the below blog. You may have an idea on Semantic Versioning.
https://www.meritedin.com/robust-api.html

Please don't forget to take a look on the videos listed on their playlist.

@DivyabharathiMurugesan commented on GitHub (Jun 29, 2021): > Should semver include provisions for normal documents or text files? A suggestion: > > For documentation not tied to a versioned software item, changes that add, delete, or move main headings (1, 2, 3, ...) should increment the Major version number. Changes to add, delete, or move subheadings (1.1, 1.2, ...) should increment the Minor version number, and changes only to body text are equivalent to Patch version changes. > > Documentation for software releases should have the version number of the document correspond to the software version it describes. To indicate textual revisions or corrections, append lower-case letters to the last digit. Thus, "3.1.5" (first version), "3.1.5a", "3.1.5b", etc. Hi, Please refer the below blog. You may have an idea on Semantic Versioning. https://www.meritedin.com/robust-api.html Please don't forget to take a look on the videos listed on their playlist.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#6420