search

opengeospatial / architecture-dwg

2 stars 3 forks source link

Consistent versioning approach on OpenAPI definition documents #25

Closed ghobona closed 1 year ago

ghobona commented 3 years ago

There is a need to harmonise the versioning approach used by SWGs while the specifications are in draft form.

cportele commented 3 years ago

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

ghobona commented 2 years ago

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

Some of the proposed solutions included:

cportele commented 2 years ago

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.

heidivanparys commented 2 years ago

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).

pebau commented 2 years ago

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 https://github.com/opengeospatial/architecture-dwg/issues/25#issuecomment-918124577, 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

ghobona commented 1 year ago

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'.