Consistent versioning approach on OpenAPI definition documents

[opengeospatial]

Consistent versioning approach on OpenAPI definition documents

[heidivanparys]

Just repeating my comment from during the Architecture DWG meeting: the original proposal presented at the meeting does not follow the semantic versioning principles as specified on https://semver.org/.

From https://semver.org/#summary:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards compatible manner, and
3. PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

See especially https://semver.org/#spec-item-9:

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.–.

Note, see also https://semver.org/#spec-item-10:

Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3—-117B344092BD.

So you could e.g. have release and pre-release versions: 1.0.0-draft.1, 1.0.0-draft.2, 1.0.0-draft.3, 1.0.0, 1.0.1.draft.1, 1.0.1, 1.1.0.

The Git commit number would be a form of build metadata (e.g. 1.0.0-draft.1+79c1702).

[cportele]

This is a general issue, not restricted to "OpenAPI definition documents".

[ghobona]

The issue was discussed during the 2021-09-13 Architecture DWG session.

Some of the proposed solutions included:

• Adding a fourth digit to semantic versioning. MAJOR.MINOR.PATCH.DRAFT-IN-PROGRESS for example 0.9.1.2
• Using Git commit numbers e.g. 79c1702d63c7f848da4e56e0b8976f93230452d5
• A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. [...] Examples: 1.0.0-alpha, 1.0.0-alpha.1

[cportele]

OGC API Features is using the 3rd approach, pre-release drafts are tagged as {x}.{y}.{z}-draft.{n} with {x}.{y}.{z} being the OGC version and {n} the pre-release number, starting with 1 for the first draft and increasing for each subsequent draft.

[pebau]

While I am very sympathetic with the model outlined below let me note that OGC in the past did NOT follow the PATCH semantics:

PATCH version when you make backwards compatible bug fixes

Patch versions explicitly do not have to maintain backwards compatibility, a fix may break it. Somebody please correct me if I'm wrong. cheers, Peter

…

On 13.09.21 14:06, Heidi Vanparys wrote: Just repeating my comment from during the Architecture DWG meeting: the original proposal presented at the meeting does not follow the semantic versioning principles as specified on https://semver.org/ <https://semver.org/>. From https://semver.org/#summary <https://semver.org/#summary>: Given a version number MAJOR.MINOR.PATCH, increment the: 1. MAJOR version when you make incompatible API changes, 2. MINOR version when you add functionality in a backwards compatible manner, and 3. PATCH version when you make backwards compatible bug fixes. Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. See especially https://semver.org/#spec-item-9 <https://semver.org/#spec-item-9>: A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.–. Note, see also https://semver.org/#spec-item-10 <https://semver.org/#spec-item-10>: Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3—-117B344092BD. So you could e.g. have release and pre-release versions: 1.0.0-draft.1, 1.0.0-draft.2, 1.0.0-draft.3, 1.0.0, 1.0.1.draft.1, 1.0.1, 1.1.0. The Git commit number would be a form of build metadata (e.g. 1.0.0-draft.1+79c1702). — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#25 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABOR5DVY2VR5TGGEMBVCYSTUBXSLJANCNFSM46X4F37A>. Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

-- Dr. Peter Baumann - Executive Director, rasdaman GmbH Bremen (HRB 26793) https://rasdaman.com, mail: ***@***.*** tel: 0800-rasdaman, fax: 0800-rasdafax, mobile: [phone] - Professor of Computer Science, Jacobs University Bremen https://www.faculty.jacobs-university.de/pbaumann mail: ***@***.*** tel: [phone], fax: [phone] "A brilliant idea is a job halfdone."

[ghobona]

To close this Issue, I note that the {x}.{y}.{z}-draft.{n} approach appears to have been the most favoured during the 2021-09-13 Architecture DWG session.

I have now listed it on a wiki page I am building that lists 'Recommended Practices for OGC API SWGs'.