[GH-ISSUE #554] clarification on "API" meaning in case of executables versioning #1269

New Issue

GiteaMirror · 2026-04-16T10:37:29-05:00

GiteaMirror commented

2026-04-16 10:37:29 -05:00

Originally created by @mastupristi on GitHub (Mar 28, 2020).
Original GitHub issue: https://github.com/semver/semver/issues/554

Throughout the text you refer to the term API (Application programming interface):

For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). 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.

The term "public APIs" makes me think of a library that should provide functionality and for this reason it is necessary to define public APIs to which the concepts of compatibility/incompatibility that drive the version change apply. Isn't that right?

But I write bare-metal executables for embedded devices. They do not expose any API. How should I implement the change of MAJOR, MINOR and PATCH?

best regards
Mac

Originally created by @mastupristi on GitHub (Mar 28, 2020). Original GitHub issue: https://github.com/semver/semver/issues/554 Throughout the text you refer to the term **API** (Application programming interface): > For this system to work, you first need to declare a **public API**. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this **API** be clear and precise. Once you identify your **public API**, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). 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. The term "public APIs" makes me think of a library that should provide functionality and for this reason it is necessary to define public APIs to which the concepts of compatibility/incompatibility that drive the version change apply. Isn't that right? But I write bare-metal executables for embedded devices. They do not expose any API. How should I implement the change of MAJOR, MINOR and PATCH? best regards Mac

GiteaMirror added the question label 2026-04-16 10:37:29 -05:00

GiteaMirror commented

2026-04-16 10:37:31 -05:00

@ljharb commented on GitHub (Mar 28, 2020):

There’s no i/o in your programs?

@ljharb commented on GitHub (Mar 28, 2020): There’s no i/o in your programs?

GiteaMirror commented

2026-04-16 10:37:31 -05:00

@mastupristi commented on GitHub (Mar 28, 2020):

There’s no i/o in your programs?

Not at all. Usually our devices have at most some LEDs, and no graphic/textual interface. They rarely have an RS485 or ethernet communication interface.
We produce pro-audio amplifiers for rack or amplified loudspeakers, so the man-machine interface is not so important.

@mastupristi commented on GitHub (Mar 28, 2020): > There’s no i/o in your programs? Not at all. Usually our devices have at most some LEDs, and no graphic/textual interface. They rarely have an RS485 or ethernet communication interface. We produce pro-audio amplifiers for rack or amplified loudspeakers, so the man-machine interface is not so important.

GiteaMirror commented

2026-04-16 10:37:32 -05:00

@ljharb commented on GitHub (Mar 28, 2020):

Sure, but they still have intended functionality - something goes in (even if that's "current" or "sound" or "a dial that goes to eleven") and something comes out ("sound" or "current" or "lights").

@ljharb commented on GitHub (Mar 28, 2020): Sure, but they still have intended functionality - something goes in (even if that's "current" or "sound" or "a dial that goes to eleven") and something comes out ("sound" or "current" or "lights").

GiteaMirror commented

2026-04-16 10:37:33 -05:00

@mastupristi commented on GitHub (Mar 28, 2020):

That's true, but the hardware does that.
Our firmware makes sure that it doesn't burn out the amplifier or the speakers connected to it, while trying to get the hardware to the highest possible limits.

@mastupristi commented on GitHub (Mar 28, 2020): That's true, but the hardware does that. Our firmware makes sure that it doesn't burn out the amplifier or the speakers connected to it, while trying to get the hardware to the highest possible limits.

GiteaMirror commented

2026-04-16 10:37:34 -05:00

@ljharb commented on GitHub (Mar 28, 2020):

Sounds like that's your API then :-) the rating/tolerance, or whatever it's called.

@ljharb commented on GitHub (Mar 28, 2020): Sounds like that's your API then :-) the rating/tolerance, or whatever it's called.

GiteaMirror commented

2026-04-16 10:37:34 -05:00

@Nyameliaaaa commented on GitHub (Mar 31, 2020):

What If The Software Is Something That Uses An API.

@Nyameliaaaa commented on GitHub (Mar 31, 2020): What If The Software Is Something That Uses An API.

GiteaMirror commented

2026-04-16 10:37:35 -05:00

@ljharb commented on GitHub (Mar 31, 2020):

What it consumes is a dependency like anything else, no? Sometimes a deps’ requirements leak and become your own, but most of the time they’re a silent implementation detail.

@ljharb commented on GitHub (Mar 31, 2020): What it consumes is a dependency like anything else, no? Sometimes a deps’ requirements leak and become your own, but most of the time they’re a silent implementation detail.

GiteaMirror commented

2026-04-16 10:37:36 -05:00

@mastupristi commented on GitHub (Mar 31, 2020):

Sounds like that's your API then :-) the rating/tolerance, or whatever it's called.

You may be right, but the boundaries aren't that sharp. Even if one wants to express them, and specify them.
Too much would be left to interpretation. It may happen that a change on one occasion may lead to a change in the MINOR number, and on another occasion it causes the MAJOR number to change.
In this context, only PATCH number changes can be clearly defined.

@mastupristi commented on GitHub (Mar 31, 2020): > Sounds like that's your API then :-) the rating/tolerance, or whatever it's called. You may be right, but the boundaries aren't that sharp. Even if one wants to express them, and specify them. Too much would be left to interpretation. It may happen that a change on one occasion may lead to a change in the MINOR number, and on another occasion it causes the MAJOR number to change. In this context, only PATCH number changes can be clearly defined.

GiteaMirror commented

2026-04-16 10:37:37 -05:00

@ljharb commented on GitHub (Mar 31, 2020):

It’s not clearly defined generically, but for any project, it can and should be explicitly defined. Minor is for additions, major is for breaking changes, patch is for everything else.

It doesn’t sound like your project would be likely to have additions, however.

@ljharb commented on GitHub (Mar 31, 2020): It’s not clearly defined generically, but for any project, it can and should be explicitly defined. Minor is for additions, major is for breaking changes, patch is for everything else. It doesn’t sound like your project would be likely to have additions, however.

GiteaMirror commented

2026-04-16 10:37:37 -05:00

@jwdonahue commented on GitHub (Apr 2, 2020):

The whole point of the SemVer spec, is to define a means for software publishers to communicate risk to their customers.

In your case, most of your products interfaces are purely electrical. There's no network protocols or API's to version for your external customers. Your production line(s) however, have different needs. Your firmware file names probably encode information about the target hardware they are intended for, and possibly other information. It's not uncommon to embed version information there as well. You may find that applying the SemVer concepts to your version strings makes sense, but it really depends on your internal processes. When you are essentially your own customer, you can evolve any system that works for you. If your mgf lines are not owned by you, you will need to establish work-flows with them, and they may have some pretty good ideas how to manage it.

@jwdonahue commented on GitHub (Apr 2, 2020): The whole point of the [SemVer](https://semver.org) spec, is to define a means for software publishers to communicate risk to their customers. In your case, most of your products interfaces are purely electrical. There's no network protocols or API's to version for your external customers. Your production line(s) however, have different needs. Your firmware file names probably encode information about the target hardware they are intended for, and possibly other information. It's not uncommon to embed version information there as well. You may find that applying the SemVer concepts to your version strings makes sense, but it really depends on your internal processes. When you are essentially your own customer, you can evolve any system that works for you. If your mgf lines are not owned by you, you will need to establish work-flows with them, and they may have some pretty good ideas how to manage it.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#1269