Is it okay to use a patch version in semver when updating documentation?

Question

How does one go about e.g. missing documentation in the source files when using semver? I have just released 1.0 of my library and noticed that a class is missing JavaDoc - is it ok to release a PATCH version? I read the semver definition but could not find anything about that topic

Answer 1

It depends on the case, and to some degree on your personal judgement:

• Adding or changing public API documentation to a package changes the package content, so you have to make a new version - see rule 3 of SemVer spec.

• Changing only the documentation does not break the API or introduce other breaking changes - so it is clear, MAJOR version number does not have to be changed.

• But does new documentation add or change any existing functionality? Rule 7 of Semver spec says:

  Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API.

So think of what the missing docs for the class you mentioned means for a user of your library:

• If the missing docs are of minor importance, and users of the class could guess the correct meaning of your class from its name, the names of the public members, and the context, then I would recommend to increment only the PATCH number. Adding the docs can be interpreted as a bug fix in this case (see rule 6 of Semver).

• If the missing docs shadow a whole feature or functionality, which is hardly usable without the documentation, then I would recommend to increment the MINOR version number (and not just the PATCH number). Here, the new docs can indeed introduce functionality to the public API.

In reality, the situation may not be that black-and-white, so you may have use your common sense if the situation fits better to the former or the latter category.