I'm learning about how to assign and increment version numbers with the rule called "Semantic Versioning" from http://semver.org/.
Among all its rules, the first one said:
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"
I am confused about "public API". What does it refer to?
Public API refers to the "point of access" that the external world (users, other programs and/or programmers, etc) have to your software.
E.g., if you're developing a library, the public API is the set of all the methods invokations that can be made to your library.
There is understanding that, unless a major version changes, your API will be backwards-compatible, i.e. all the calls that were valid on a version will be valid on a later version. You can read at point 9 of those rules:
Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.
I discovered SemVer today and read up on it from several sources to ensure I had fully grasped it.
I am confused about "public API". What does it refer to?
I was also confused about this. I wanted to set about using SemVer immediately to version some of my scripts, but they didn't have a public API and it wasn't even clear to me how they could have one.
The best answer I found is one that explains:
SemVer is explicitly not for versioning all code. It's only for code that has a public API.
Using SemVer to version the wrong software is an all too common source of frustration. SemVer can't version software that doesn't declare a public API.
Software that declare a public API include libraries and command line applications. Software that don't declare a public API include many games and websites. Consider a blog; unlike a library, it has no public API. Other pieces of software cannot access it programmatically. As such, the concept of backward compatibility doesn't apply to a blog. As we'll explain, semver version numbers depend on backward compatibility. Because of this dependence, semver can't version software like blogs.
It requires a public API in order to effectively apply it's versioning pattern.
For example:
Bug fixes not affecting the API increment the patch version
Backwards compatible API additions/changes increment the minor version, and...
Backwards incompatible API changes increment the major version.
What represents your API is subjective, as they even state in the SemVer doc:
This may consist of documentation or be enforced by the code itself.
Having read the spec a few times,
- 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.
I wonder whether all it means is that the consumers of your software must be able to establish the precise "semantic" version they are using.
For example, I could produce a simple script where the semantic version is in the name of the script:
DoStuff_1.0.0.ps1
It's public and precise. Not just in my head :)
Semantic versioning is intended to remove the arbitrariness that can be seen when someone decides to select a versioning scheme for their project. To do that, it needs rules, and a public API is a rule that SemVer chose to use. If you are building a personal project, you don't need to follow SemVer, or follow it strictly. You can, for example, choose to loosely interpret is as
But the vagueness of this loose interpretation opens you up to arbitrariness again. That might not matter to you, or the people you foresee who will be using your software.
The larger your project is, the more the details of your versioning scheme matters. As someone who has worked in a third level support for a large IT company (which licenses APIs to customers) for quite some time, I have seen the "is it a bug or is it a feature" debate many times. SemVer intends to make such distinctions easier.
A public API can, of course, be a REST API, or the public interface of a software library. The public/private distinction is important, because one should have the freedom to change the private code without it adversely affecting other people. (If someone accesses your private code through, say, reflection, and you make a change which breaks their code, that is their loss.)
But a public API can even be something like command line switches. Think of POSIX compliant CLI tools. These tools are standalone applications. But they are used in shell scripts, so the input they accept, and the output they produce, can matter. The GNU project may choose to reimplement a POSIX standard tool, and include its own features, but in order for a plethora of shell scripts to continue working across different systems, they need to maintain the behaviour of the existing switches for that application. I have seen people having to build wrappers around applications because the output of the version command changes, and they had scripts relying on the output of the version command to be in a certain form. Should the output of the version command be part of the public API, or is what those people using it did a hack? The answer is that it is up to you and what guarantees you make to the people using your software. You might not be able to imagine all use cases. Declaring the intended use of your software creates a contract with your users, which is what a public API is.
SemVer, thus, makes it easier for your uses to know what they are getting when upgrading. Did only the patch level change? Yes, so better install it quick to get the latest patch fix. Did the major version change? Better run a full, potentially expensive, regression test suite to see if my application will still work after the upgrade.
