1

All,We need a convention to assign a version number for our product. After I research. I found this post answer my question. And it lead me to the http://semver.org/, The Semantic Versioning Specification.

I think almost everything in the Semantic Versioning make sense to me .But only one thing I didn't understand . In the Semantic Versioning Specification Rule No1. Please help to review it .

Software using Semantic Versioning MUST declare a public API.

I can't understand what does public API mean.

In our products. We have all kinds of format software. like executable program, library, web site etc. Some of them without public API, like executable program. IMO, I think the Public API means some public methods or functions which can be referenced and called by other software. like Fo-Dicom which is a Class Library, can be referenced by another project. Without Graphic UI. Just provide a group of API to deal with DICOM file based on the .Net Framework. So My question is what exactly the Public API mean in the Semantic Versioning? What kind of products are not suitable for Semantic Versioning? Thanks.

Joe.wang
  • 113
  • 6
  • Take a look [here](https://softwareengineering.stackexchange.com/q/239082/222996). Obviously, if there's no public API, there's no interface where apply the samantic rules. – Laiv Aug 21 '17 at 08:13
  • 1
    Or this [one](https://softwareengineering.stackexchange.com/a/351833/222996) where J.W.M explains how semversion coexists with other sort of versionings – Laiv Aug 21 '17 at 08:24
  • Hi Laiv, Thank you for the link, It is exactly what I tried to asked. – Joe.wang Aug 22 '17 at 02:47
  • But after reading . I still have no idea what does the public API mean. Forgive me my poor understanding. – Joe.wang Aug 22 '17 at 02:52
  • 1
    By API I understand something that can be consumed/implemented by other code. Could be code, configurations, specifications, SDKs. Anything that can be subject to the semantic rules. For example, I would find hard to use Semver for a O.S but adequate for its libraries. – Laiv Aug 22 '17 at 08:12
  • @Laiv Thanks for your reply, It is better understanding now. – Joe.wang Sep 17 '17 at 15:11

2 Answers2

3

Your understanding of public API is correct: Public API is anything that is consumed by another software outside of your team's direct control (e.g. on another release cycle). This can apply to anything from classes or methods to configuration, web services, server addresses, or more.

Semantic versioning is a method of dependency management, so it assumes other software components that depend on your public API. Rule No 1 wants you to identify these parts of your software and make them explicit. If your software has no such parts, you don't stricly need semantic versioning - but it can still be a good idea, as your users might care.

Flo F
  • 101
  • 3
1

According to their definition, the major version is supposed to change whenever you make a change that makes the public API incompatible with the old version. Taken literally, something without a public API can't have a meaningful major version number.

Any library must have an API - it's the set of functions that the library exposes to its users. Command-line programs effectively have an API in the set of command line parameters. Some other executables have a way to drive them remotely, for instance via a network link. I don't think it's important to worry about exactly what you mean by "API".

The important thing is that, you should consider a major version to be any change that breaks compatibility with a previous version. This could include changes in the files that the software reads or writes.

Simon B
  • 9,167
  • 4
  • 26
  • 33