Proposed addendum: How MAJOR.MINOR.PATCH applies to docs #522

New Issue

2026-02-17T12:11:25-06:00

GiteaMirror commented

2026-02-17 12:11:25 -06:00

Originally created by @camerons on GitHub (Jan 3, 2022).

Within the tech writing space, we would benefit from a common understanding about what MAJOR, MINOR, and PATCH means when applied to documentation.

As a tech writer, I'm personally motivated to try and solve this and work with others toward a solution. Immediate needs I'm aware of:

For specifications we are drafting at Google.
For documentation templates we are developing within The Good Docs Project. (Open source project creating documentation templates for open source documentation.)

We've drafted a possible semantic versioning addendum for documents, and are looking for:

Feedback on our proposal.
- Feel free to add comments to the Google Doc, but don't add track changes as it makes it too hard to read.
- If there is sufficient interest, I'm happy to convert this to a pull request if that helps.
Pointers to any related initiatives which we could defer to if they exist.
Introductions to potential collaborators.

Originally created by @camerons on GitHub (Jan 3, 2022). Within the tech writing space, we would benefit from a common understanding about what MAJOR, MINOR, and PATCH means when applied to documentation. As a tech writer, I'm personally motivated to try and solve this and work with others toward a solution. Immediate needs I'm aware of: 1. For specifications we are drafting at Google. 2. For documentation templates we are developing within [The Good Docs Project](https://thegooddocsproject.dev). (Open source project creating documentation templates for open source documentation.) We've drafted a possible [semantic versioning addendum for documents](https://docs.google.com/document/d/1gPr_OHoUkg5Wjj3UWYX78ORtTBArSJck4mWrKhWpfPA/edit), and are looking for: * Feedback on our proposal. * Feel free to add comments to the Google Doc, but don't add track changes as it makes it too hard to read. * If there is sufficient interest, I'm happy to convert this to a pull request if that helps. * Pointers to any related initiatives which we could defer to if they exist. * Introductions to potential collaborators.

GiteaMirror commented

2026-02-17 12:11:26 -06:00

@ljharb commented on GitHub (Jan 3, 2022):

Why does documentation need a way to convey breakage?

@ljharb commented on GitHub (Jan 3, 2022): Why does documentation need a way to convey breakage?

GiteaMirror commented

2026-02-17 12:11:26 -06:00

@camerons commented on GitHub (Jan 4, 2022):

@ljharb
Some, but not all documentation types can break backwards compatibility. An update to a blog or news post typically won't break compatibility. Doc types which may break backward compatibility include:

Standards and specifications, such as for describing an API.
Reference documentation for a product, which breaks compability when the product being documented breaks compatibility.
A change of documentation license from sharable to restricted. For instance, changing new versions a standard from CC-By to being behind an ISO paywall, which prevents open source communities from using the standard.

@camerons commented on GitHub (Jan 4, 2022): @ljharb Some, but not all documentation types can break backwards compatibility. An update to a blog or news post typically won't break compatibility. Doc types which may break backward compatibility include: * Standards and specifications, such as for describing an API. * Reference documentation for a product, which breaks compability when the product being documented breaks compatibility. * A change of documentation license from sharable to restricted. For instance, changing new versions a standard from CC-By to being behind an ISO paywall, which prevents open source communities from using the standard.

GiteaMirror commented

2026-02-17 12:11:26 -06:00

@ljharb commented on GitHub (Jan 4, 2022):

It seems like you just answered your own question then?

@ljharb commented on GitHub (Jan 4, 2022): It seems like you just answered your own question then?

GiteaMirror commented

2026-02-17 12:11:26 -06:00

@camerons commented on GitHub (Jan 5, 2022):

@ljharb
It is possible you haven't yet read the proposed semantic versioning addendum for documents? Yes, we have a proposed interpretation of MAJOR.MINOR.PATCH for docs.

Our goal is to establish a widely recognized and acknowledged standard for semantic versioning as applied to documentation. Ideally, this would done in conjunction with, and with the blessing and support of the https://semver.org/ community, and would complement and extend https://semver.org/ rather than compete with it.

What would be next steps to collaborate with the https://semver.org/ community? Would it help to start with an initial video conference call?

@camerons commented on GitHub (Jan 5, 2022): @ljharb It is possible you haven't yet read the proposed [semantic versioning addendum for documents](https://docs.google.com/document/d/1gPr_OHoUkg5Wjj3UWYX78ORtTBArSJck4mWrKhWpfPA/edit)? Yes, we have a proposed interpretation of MAJOR.MINOR.PATCH for docs. Our goal is to establish a widely recognized and acknowledged standard for semantic versioning as applied to documentation. Ideally, this would done in conjunction with, and with the blessing and support of the https://semver.org/ community, and would complement and extend https://semver.org/ rather than compete with it. What would be next steps to collaborate with the https://semver.org/ community? Would it help to start with an initial video conference call?

GiteaMirror commented

2026-02-17 12:11:27 -06:00

@ljharb commented on GitHub (Jan 5, 2022):

Ah, thanks, I’d misunderstood the purpose of this issue.

@ljharb commented on GitHub (Jan 5, 2022): Ah, thanks, I’d misunderstood the purpose of this issue.

GiteaMirror commented

2026-02-17 12:11:27 -06:00

@jwdonahue commented on GitHub (Jan 10, 2022):

@camerons This seems like the right approach to me.

Proposed 6.1 e & f have the word "addition" in them, implying in my mind that a minor bump should apply. Notes, cross references and metadata are document features, as such, adding any of these is adding a feature to the document. There may even be situations where adding a document author or license could be a breaking change.

Proposed 7.1 d raises the similar concerns, particularly if a less restrictive license is removed where a more restrictive license would then be in force.

Proposed 8.1 SHOULD is weaker than the SemVer spec's MUST wrt incompatible changes.

@jwdonahue commented on GitHub (Jan 10, 2022): @camerons This seems like the right approach to me. Proposed 6.1 e & f have the word "addition" in them, implying in my mind that a minor bump should apply. Notes, cross references and metadata are document features, as such, adding any of these is adding a feature to the document. There may even be situations where adding a document author or license could be a breaking change. Proposed 7.1 d raises the similar concerns, particularly if a less restrictive license is removed where a more restrictive license would then be in force. Proposed 8.1 SHOULD is weaker than the SemVer spec's MUST wrt incompatible changes.

GiteaMirror commented

2026-02-17 12:11:27 -06:00

@spaceChRiS commented on GitHub (Feb 26, 2022):

I wonder if it would make sense to add information how a document's versioning should be handled if it has a close lifecycle to a software, e.g. a user manual for the software. In this case, it may make sense that the major number belongs to the software revision but the patchlevel belongs purely to the document changes. For the minor number, I am not sure which makes more sense.

@spaceChRiS commented on GitHub (Feb 26, 2022): I wonder if it would make sense to add information how a document's versioning should be handled if it has a close lifecycle to a software, e.g. a user manual for the software. In this case, it may make sense that the major number belongs to the software revision but the patchlevel belongs purely to the document changes. For the minor number, I am not sure which makes more sense.

GiteaMirror commented

2026-02-17 12:11:28 -06:00

@jwdonahue commented on GitHub (Feb 27, 2022):

I wonder if it would make sense to add information how a document's versioning should be handled if it has a close lifecycle to a software, e.g. a user manual for the software. In this case, it may make sense that the major number belongs to the software revision but the patchlevel belongs purely to the document changes. For the minor number, I am not sure which makes more sense.

The document version and the product version need not sync up at all. The document my be labeled "Rev H" or just "YYYY-MM-DD. It's presence in the product packaging is one linkage to the product, the other might be the embedded product version somewhere in the document (title/sub-title).

@jwdonahue commented on GitHub (Feb 27, 2022): > I wonder if it would make sense to add information how a document's versioning should be handled if it has a close lifecycle to a software, e.g. a user manual for the software. In this case, it may make sense that the major number belongs to the software revision but the patchlevel belongs purely to the document changes. For the minor number, I am not sure which makes more sense. The document version and the product version need not sync up at all. The document my be labeled "Rev H" or just "YYYY-MM-DD. It's presence in the product packaging is one linkage to the product, the other might be the embedded product version somewhere in the document (title/sub-title).

GiteaMirror commented

2026-02-17 12:11:28 -06:00

@ahenket commented on GitHub (May 13, 2022):

Thanks. Read it and added a comment

@ahenket commented on GitHub (May 13, 2022): Thanks. Read it and added a comment