CODEWITHSUNDEEP
semantic-versioning
Hervé
Hervé

Reputation: 85

HTTP Restful Semantic Versioning

Currently, I use the semantic versioning for an API.

Versioning is envolves like this:

Should I increment the PATCH, if I only update the documentation (swagger, internal documenation, YAML, ...) to add example, or correct a description attach to the API?

Thanks for your help ;)

Upvotes: 2

Views: 177

Answers (1)

jwdonahue
jwdonahue

Reputation: 6659

Should I increment the PATCH, if I only update the documentation (swagger, internal documenation, YAML, ...) to add example, or correct a description attach to the API?

Depends on the example/correction. Does it represent a break from previous understanding of the use of your API's? Here's a very contrived example for discussion:

API: int plus(int a, int b)

Documentation: int plus(int a, int b) sums a + b.

The above was released as 1.0.0, then someone reviews the code and points out that on overflow, the function returns 0.

Updated documentation: int plus(int a, int b) sums a + b where a < 32767 and b < 32767, otherwise, returns 0.

So, whether this is a breaking change, depends on the language and its behavior when a + b overflow. Some languages throw an exception or segfault, others, it's common for them to simply return a modulo result of some kind. Let's say it's C, in that case, this documentation change is likely a breaking change (well, probably most programming languages actually).

The point here is that initial documentation is often not much better than a superficial restatement of the API itself. Subsequent complaints (bug reports) from customers, often drive the next round of documentation changes, when the customers are surprised by the results. So yes, even though the original intent of the developer hasn't changed, the documentation does represent a breaking change in regard to the expected results.

Had the documentation been changed to match exactly what the customers expected/witnessed in use, then no, it's not a breaking change.

The documentation is part of the feature set. Back-filling missing documentation is usually a feature addition, so you'd bump the minor version. A minor correction would be a patch.

Upvotes: 2

Related Questions