3 ms·

Semantic versioning is for APIs, not for functionality. So it's for developers consuming that API (whether a library, or a service). For releases in production

by rswail 1y ago

Semantic versioning is for APIs, not for functionality. So it's for developers consuming that API (whether a library, or a service). For releases in production, use a calendar version. v2025-11-02 is a clear release tag. Add preciseness as required. There should be a SBOM/Manifest (Bill Of Materials) of the versioned major components and configuration for that overall release. For users, it depends on the type of user and what they expect. Their focus is on functionality. So when there's a new feature, bump the number. It's a bit like the car model. It can be random extension letters like "-X", or "6Si".

necovek 1y ago
Developers are "users" (of a library, API, tool...), and "API functionality" is a subset of "functionality": what purpose would such distinction serve? For example, in end user desktop software (say a text editor), how would you indicate a security bug fix for an old version v2023-11-02 without forcing users to pay for a new version of v2025-09-15? Again, versioning is a tool, and depending on the release structure of a project, SemVer might work well or it might not (including for APIs/libraries).
- rswail 1y ago
  Semver is semantic. It tells you about the changes in the API, not in the implementation. So it's relevant to the users (ie developers) of that API. If I fix a bug in the implementation that doesn't affect the API itself, the semver doesn't change. So it works to define the versioning of an interface. Release versioning (like vyyyy-mm-dd) is about SRE and configuration management, it's about documenting what is actually operating in production. User versioning is about user expectations. If you're doing a security bug fix, then a) it should be free to users affected, and b) it should be documented as the reason for the release. For a security bug fix of v2023-11-02, you can add a "hotfix" extension to the numbering so v2023-11-02.001 or equivalent.
  - necovek 1y ago
    I can see how you are using the multiple versioning schemes to achieve certain goals, but that does not make your approach "one true way". "Semantic" really means "has some background meaning", and SemVer meaning behind all the numbers is in no way limited to API versioning: I am confused if you are making a proposal to consider it only that, arguing that different schemes should be used for different types of software, or stating that this is the only thing SemVer can be used for? On any of those points, I disagree and you haven't made a convincing argument why that would make sense. Note that I am not saying that SemVer is the only true way to do versioning (very much not so) for all software, just that it depends on your release strategy what is most applicable, and not on the type of software you are shipping.
    - rswail 1y ago
      The original reasoning behind Semver was that it described the changes from the point of view of the consumer of the interface. If the interface didn't change, then the semver didn't change. So yes, I am arguing it should not be used beyond that. Horses for courses... semver is about semantic meaning to the consumer of an interface, release versioning is about configuration and SRE, user versioning is about functionality and (for a client app) security. As for proposing the "One True Way", no, I'm not proposing that, I'm saying that I use 3 different versioning strategies for 3 different use cases. In a production system that I am involved with, the current production is: API: v5.0.0 (yes we just introduced major breaking changes, however, we have an endpoint for older semvers) Release: v2025-10-30 (with release notes saying which API Semvers were available and which versions of the user app) User app: v3.5.1 (there was a security patch to v3.5)
      - necovek 1y ago
        But very similar versioning schemes have been used by different software for a long time before SemVer was formalized as such: again, if you accept any user interface as the interface, vs API interface (or interfaces for developers) as you originally proposed, I have no issue with that. Eg. GNU coding standards[1] said the following at least 18 years ago: You should identify each release with a pair of version numbers, a major version and a minor. We have no objection to using more than two numbers, but it is very unlikely that you really need them. I'd also note that your user app versioning seems to use the same approach. [1] https://cvs.savannah.gnu.org/viewvc/gnustandards/gnustandards/standards.texi?revision=1.169&view=markup#l3966 https://cvs.savannah.gnu.org/viewvc/gnustandards/gnustandard...
roryirvine 1y ago
Oracle used to do that, didn't they? So, amongst others, they had Oracle 8i at the height of the dot com boom (i for "Internet"), then a few years later when clustering became big news there was Oracle 10g (the g standing for "grid", I think?), and so on. Actually, it looks like they might still be doing it - I just checked, and their current version is 23ai...
- rswail 1y ago
  Exactly. There's nothing specific about the letters after Oracle's RDBMS versions, they're for marketing purposes.

by rswail 1y ago

necovek 1y ago

Developers are "users" (of a library, API, tool...), and "API functionality" is a subset of "functionality": what purpose would such distinction serve? For example, in end user desktop software (say a text editor), how would you indicate a security bug fix for an old version v2023-11-02 without forcing users to pay for a new version of v2025-09-15? Again, versioning is a tool, and depending on the release structure of a project, SemVer might work well or it might not (including for APIs/libraries).

rswail 1y ago
Semver is semantic. It tells you about the changes in the API, not in the implementation. So it's relevant to the users (ie developers) of that API. If I fix a bug in the implementation that doesn't affect the API itself, the semver doesn't change. So it works to define the versioning of an interface. Release versioning (like vyyyy-mm-dd) is about SRE and configuration management, it's about documenting what is actually operating in production. User versioning is about user expectations. If you're doing a security bug fix, then a) it should be free to users affected, and b) it should be documented as the reason for the release. For a security bug fix of v2023-11-02, you can add a "hotfix" extension to the numbering so v2023-11-02.001 or equivalent.
- necovek 1y ago
  I can see how you are using the multiple versioning schemes to achieve certain goals, but that does not make your approach "one true way". "Semantic" really means "has some background meaning", and SemVer meaning behind all the numbers is in no way limited to API versioning: I am confused if you are making a proposal to consider it only that, arguing that different schemes should be used for different types of software, or stating that this is the only thing SemVer can be used for? On any of those points, I disagree and you haven't made a convincing argument why that would make sense. Note that I am not saying that SemVer is the only true way to do versioning (very much not so) for all software, just that it depends on your release strategy what is most applicable, and not on the type of software you are shipping.
  - rswail 1y ago
    The original reasoning behind Semver was that it described the changes from the point of view of the consumer of the interface. If the interface didn't change, then the semver didn't change. So yes, I am arguing it should not be used beyond that. Horses for courses... semver is about semantic meaning to the consumer of an interface, release versioning is about configuration and SRE, user versioning is about functionality and (for a client app) security. As for proposing the "One True Way", no, I'm not proposing that, I'm saying that I use 3 different versioning strategies for 3 different use cases. In a production system that I am involved with, the current production is: API: v5.0.0 (yes we just introduced major breaking changes, however, we have an endpoint for older semvers) Release: v2025-10-30 (with release notes saying which API Semvers were available and which versions of the user app) User app: v3.5.1 (there was a security patch to v3.5)
    - necovek 1y ago
      But very similar versioning schemes have been used by different software for a long time before SemVer was formalized as such: again, if you accept any user interface as the interface, vs API interface (or interfaces for developers) as you originally proposed, I have no issue with that. Eg. GNU coding standards[1] said the following at least 18 years ago: You should identify each release with a pair of version numbers, a major version and a minor. We have no objection to using more than two numbers, but it is very unlikely that you really need them. I'd also note that your user app versioning seems to use the same approach. [1] https://cvs.savannah.gnu.org/viewvc/gnustandards/gnustandards/standards.texi?revision=1.169&view=markup#l3966 https://cvs.savannah.gnu.org/viewvc/gnustandards/gnustandard...

roryirvine 1y ago

Oracle used to do that, didn't they? So, amongst others, they had Oracle 8i at the height of the dot com boom (i for "Internet"), then a few years later when clustering became big news there was Oracle 10g (the g standing for "grid", I think?), and so on. Actually, it looks like they might still be doing it - I just checked, and their current version is 23ai...

rswail 1y ago
Exactly. There's nothing specific about the letters after Oracle's RDBMS versions, they're for marketing purposes.