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.
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?
<!-- gh-comment-id:686157038 -->
@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?
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.
<!-- gh-comment-id:758383349 -->
@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.
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).
<!-- gh-comment-id:779461903 -->
@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).
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.
<!-- gh-comment-id:779469594 -->
@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.
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.
<!-- gh-comment-id:779503121 -->
@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.
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.
<!-- gh-comment-id:779548570 -->
@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.
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.
<!-- gh-comment-id:779553206 -->
@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):
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.
Please don't forget to take a look on the videos listed on their playlist.
<!-- gh-comment-id:870768703 -->
@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.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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.
@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.