[GH-ISSUE #69] Semantic Versioning of Public API Too ? #1788

New Issue

GiteaMirror · 2026-04-20T09:23:26-05:00

GiteaMirror commented

2026-04-20 09:23:26 -05:00

Originally created by @pignace on GitHub (Mar 5, 2013).
Original GitHub issue: https://github.com/semver/semver/issues/69

In the software products sector there is a need to maintain several implementations of the same public API, as several software products can implement the same interface (with different technologies or different capacities for instance).

Standard public APIs are versioned. For instance in the JEE world : Servlet (1.0,2.0,2.1... 3.0), JMS (1.0 & 1.1), JPA (1.0,2.0), EJB ( ..). Out of JEE : SNMP V1,V2,V2.C,V3

That raise some questions :
1 : The semantic versioning scheme might be too rich for "public API". But a two number scheme (X.Y) with the same backward compatibility rules seems fine.

2 : The issue that I see is a redundancy between the API scheme and the implementation scheme. Does it still makes sense to couple X. in a product and X. in an API ?

Originally created by @pignace on GitHub (Mar 5, 2013). Original GitHub issue: https://github.com/semver/semver/issues/69 In the software products sector there is a need to maintain several implementations of the same public API, as several software products can implement the same interface (with different technologies or different capacities for instance). Standard public APIs are versioned. For instance in the JEE world : Servlet (1.0,2.0,2.1... 3.0), JMS (1.0 & 1.1), JPA (1.0,2.0), EJB ( ..). Out of JEE : SNMP V1,V2,V2.C,V3 That raise some questions : 1 : The semantic versioning scheme might be too rich for "public API". But a two number scheme (X.Y) with the same backward compatibility rules seems fine. 2 : The issue that I see is a redundancy between the API scheme and the implementation scheme. Does it still makes sense to couple X. in a product and X. in an API ?

GiteaMirror closed this issue

2026-04-20 09:23:26 -05:00

GiteaMirror commented

2026-04-20 09:23:27 -05:00

@colin-haber commented on GitHub (Mar 5, 2013):

There's no need to make a different versioning scheme, though. Even if you're versioning an API standard or specification, not its implementations, (so there's no need for patches,) you can still use the three-number scheme. The patch version will just be rarely used.

Making up a whole new standard for public APIs is the exact opposite goal of SemVer. Why not just use what it provides, as it's literally more than enough to cover your needs?

@colin-haber commented on GitHub (Mar 5, 2013): There's no need to make a different versioning scheme, though. Even if you're versioning an API standard or specification, not its implementations, (so there's no need for patches,) you can still use the three-number scheme. The patch version will just be rarely used. Making up a whole new standard for public APIs is the exact opposite goal of SemVer. Why not just use what it provides, as it's literally more than enough to cover your needs?

GiteaMirror commented

2026-04-20 09:23:28 -05:00

@haacked commented on GitHub (Mar 13, 2013):

Yeah, I agree with dgn1nja. Also, what you choose to use in your "marketing" version doesn't have to match the actual version number.

So your interface might be communicated as "1.0" but the actual implementations in code (the part anyone would take a physical dependency on) would be "1.0.0" or "1.0.9". Doesn't really matter.

@haacked commented on GitHub (Mar 13, 2013): Yeah, I agree with dgn1nja. Also, what you choose to use in your "marketing" version doesn't have to match the actual version number. So your interface might be communicated as "1.0" but the actual implementations in code (the part anyone would take a physical dependency on) would be "1.0.0" or "1.0.9". Doesn't really matter.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#1788