Make full use of GitHub releases - release number json schema's

[j-ventura]

GitHub has a native implementation of releases. Rather than make use of files for release notes and include version number in file names it would be better if this project would make use of this feature.

Currently the repo looks as follows:

With version numbers and release notes as files in the repo.

But we can use something like this:

GitHub releases basically leverage the concept of tag, where a particular commit in the git history receives a description with or without additional metadata. Using tags (releases) provides a number of benefits:

• Consumers of the repo can be sure that all the files in a release are in a consistent state (basically behaving as a snapshot)
• A release is immutable and as such can be used as a point of reference in automated systems, with the guarantee that its content will not change

Furthermore, releases should follow semantic versioning, with a schema like xx.yy.zz:

• Major versions (xx) incremented when breaking changes occur such as:

  • Changes in data types
  • Removal/Addition of mandatory fields
  • Renaming of endpoints
  • Removing endpoints

  Basically any change that renders older clients incompatible with the new spec, meaning that clients from previous versions would no longer be able to interact with the service, on the new version.

• Minor versions (yy) incremented for non breaking changes such as:

  • Increasing the size/limits of fields
  • Adding new optional fields
  • Adding new endpoints

  Basically changes where older clients will still retain full functionality when interacting with a newer version of the API.

• Patches (zz) for changes that are transparent for consumers such as:

  • Updates to documentation
  • Updates to descriptions

  Basically changes that require no updates on the part of the clients consuming the API, implying no changes in any of the payloads.

In the schema files are being generated with version numbers in them, these should be stripped out before the files are committed to git so that information regarding versions is only captured via the tagging strategy.

Best regards,

Joaquim

[kooskaspers]

Hi @j-ventura, I endorse this ideology of making use of tags and releases.