How to Understand Semantic Versioning's Requirement for a Public API

I’ve got the gist of the semantic versioning specification . My question arises in regard to this:

Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive.

An API declared in code is straight forward. Please help me picture an API that exists strictly in documentation. Can this mean any documentation that explains how to use the software and as long as changes don’t contradict existing documentation the major version isn’t incremented? Or am I interpreting it all wrong?

Thanks!

My interpretation of that statement is best expressed by changing the word “strictly” with “explicitly”.

This API could be declared in the code itself or exist explicitly in documentation.

Particularly with the could earlier in the sentence, I think what the author means to suggest it doesn’t really matter where the API is defined, but it matters very much that the definition is strict and explicit. You should not have bits and pieces scattered around the documentation indicating different ways to interact with the program. There should pretty much be one page listing valid calls and expected responses with changes between versions noted.

Relating to the second part of your question, given a version number 0.x.x, if I build an application using your package and I follow the API no version change where only an x changes should break my program. Only major version changes should not be completely backwards compatible with all previous APIs.

1 Like