mirror of
https://github.com/semver/semver.git
synced 2026-07-11 04:52:47 -05:00
Applying Semantic Versioning to documentation #430
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#430
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @epement-db on GitHub (Sep 2, 2020).
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.
@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?
@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):
Appending letters to the version is out of SemVer's scope.
@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).
@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.
@Nixinova commented on GitHub (Feb 16, 2021):
Answered by ...
Yes but not how you used it: 1.0.0, 1.0.0+doc.1, 1.0.0+doc.2, etc.
@ghost commented on GitHub (Feb 16, 2021):
That's not so obvious from reading the SemVer specification for patching:
@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.
@DivyabharathiMurugesan commented on GitHub (Jun 29, 2021):
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.