Define initial version scheme

[cookeac]

This is version 1.0 (or pre-1.0) but eventually there will be later versions, and clients and servers may need to distinguish. It would be wise now to recommend a versioning scheme. There are two components to this:

1. Version representation - most APIs are now using SemVer or equivalent (major + minor, breaking changes only in major). Its likely we could do this or indeed only worry about major.

2. Versioning strategy - there are four common methods:
   a. Include version in the URL specification (challenging initially if we are not insisting on a URL format, and forces servers to implement multiple API URLs).
   b. Include version in the URL Query String (?version=1)? Not often used.
   c. Use custom version headers ("accepts-version: 1.0"). Means testing with a browser is extra work.
   d. Use content negotiation (“Accept: application/vnd.xm.device+json; version=1” ). Elegant but much harder to test APIs with a browser.

For instance, see https://restfulapi.net/versioning/

[lkoivuka]

1. As far as api consumers go, breaking changes are the critical ones where change is required to consume/interact with the new version (and in case of eventual deprecation). If the standard is tolerant to change, per evolving the standard, would it be most forward thinking to ensure that the consumer can support additional fields when desired (non breaking changes) without impact, which seems to imply that minor/patches should not require changes to the version. As long as it's additions to the standard it seems like major could be sufficient and reserved for breaking changes. Perhaps the version could or should be included for information and awareness to keep track of what has changed even if it's non-breaking.

A big question is which versioning strategy. It doesn't necessarily have to be resolved day 1 but limits the options (or introduces breaking changes) once standardized.

2. d.
   Another interesting read on versioning recommends avoiding the standard Accept and Content-type headers, instead opting for custom headers.

The content negotiation versioning could potentially tie into the decision on Hypermedia, at least in the case of HATEOS.

[cookeac]

Version Management was raised at the meeting on 31 January 2020.

There are many aspects to versioning. Among them:

1. Using a versioning scheme to communicate to developers and implementers the state of the standard and its relationship to a previous or later version that they might be familiar with. This includes helping people to understand which versions might be incompatible.
2. Managing the development and release process of standards.
3. Helping software to automatically determine whether APIs are compatible, or which version of an API to use, or how to format content (content negotiation).

The last point is discussed in #17 (comment) above.

I have recommendations to make regarding the first two points, based on other open source standard schemes.

Recommendation: for communication, use Semantic Versioning 2.0.0 (https://semver.org/).

• change to major version indicates a breaking change
• change to minor version indicates a planned functional release (e.g. new message)
• change to patch version indicates a fix to the specification

Recommendation: for development and release process after 1.0 release, use the GitFlow branching model (https://nvie.com/posts/a-successful-git-branching-model/).
In this approach:

• Master contains the official releases
• Each release is tagged with its version, so you can get earlier published versions.
• Develop branch (in the icar/adewg repository and all forks) is used for new developments/updates and pull requests.
• When the WG agrees a release is "ready" we merge back from Develop to Master and tag the new release.

This sounds like a bit of extra work, but is not really too complex, and will help others who want to understand what is ready and what is in development.

[ahokkonen]

I agree on this proposal for both scheme version and development aspects.

As I understood with working on first major version we will be having 2 branches master (for official releases) and develop (for ongoing development). At the time we starting to work on second major release 2.x original v1.x will be extracted to own branch (like hotfix/1.x) for patching support purposes?

[cookeac]

After listening to the recording of our meeting on 14 February (to write the minutes), my summary is:

1. Semantic versioning - yes, adopted.
2. Develop branch (once 1.0 is released) - yes, new developments go in here.
3. Do not have a MASTER branch, but have a branch for each major version - for instance 1.0, 2.0 (more about the labelling in a moment). This enables maintenance of the previous major (breaking) version.
4. Within a version branch, use Tags to label minor and patch releases. These are non-breaking.
5. When implementations are built, include only the major (breaking) version in the URL

My further proposal to this is that rather than just V1 or V2 for major versions in branch names and URLs, we make it something recognisable such as ADE-1 or ADE-2 and use this in both branch names and URLs (I think the branch name and the URL identifier should be the same, regardless of whether this is ADE-1, V1, ICAR1, or something else).

[alamers]

I like the ADE-1 name scheme: the "v" in v1 doesn't add any value. (And it solves a small issue with us at JoinData on already having used 'v1' ;) ).

[cookeac]

Version scheme has now been documented as agreed, the Develop branch has been created, and the ADE-1 branch has been made the default to help new users use the specifications. Contributors should now use the Develop branch.