Moving forward with this project's versioning

[aeneasr]

Hi there,

so I kinda messed up. This project is currently released as version v1.0.0-beta.X. The goal of this was to have one coherent version across all services to make integration of them as easy as possible. While that was a good intention, releasing something as v1.0.0 gave the wrong impression of stability, and rightful so. My initial idea was to label projects that are not fully backed yet with a -sandbox or -preview tag (v1.0.0-sandbox) but that contradicts how semantic versioning works and is probably even more confusing.

For so many reasons this was a bad decision, this project specifically moved right away from v0.0.29 to v0.11.0 to v1.0.0 - instead of going through a "sandbox" or "graduating" phase where you, the community, evaluates the usefulness of the service and gives feedback on missing parts which may require breaking changes.

To resolve this, we worked on a new concept which I would like to present to you here. To not make the same mistake again, I want to get your feedback on this before moving forward with this plan. Implementing this plan implies that versions v1.0.0-beta.* will be purged and that we will start tagging this as a v0.y.z release instead.

Please read (and give feedback) on the following paragraphs which will be (upon approval) immortalized in the ORY Documentation:

Software Versions

The ORY ecosystem consists of multiple services versioned using semantic versioning. This section explains how we define service versions and what they mean.

There are two types of services:

• Graduated services change rarely in a backwards incompatible fashion. A service can be considered graduated if the major version is >= 1 - for example: v1.0.1, v2.2.2. If a serious backwards incompatible change is made, the major version jumps one up. Most, if not all, REST APIs will provide backwards compatible transformations that make it possible to interact with the server using older API concepts.
• Incubating services have well defined concepts but do not provide backwards compatible REST APIs yet. Incubating services are indicated by major version numbers of 0 - for example: v0.10.0
• Sandbox services may implement concepts, provide APIs and CLIs which are not fully baked yet. It is possible that these services change in unpredictable ways. These services are indicated by major version numbers of 0 and the sandbox label - for example: v0.10.0-sandbox.

To make deployment easier but stay compatible with semantic versioning, each service is equipped with a ecosystem version number denoted by +oes.X where X represents the version ecosystem. This is specifically useful when using incubating or sandboxed services which do not share the version numbers of graduated services. Let's look at some examples:

• ORY Hydra v1.0.1+oes.6 is best compatible with ORY Oathkeeper v0.12.1+oes.6 and ORY Keto v0.5.1-sandbox+oes.6.
• ORY Hydra v1.0.2+oes.7 is best compatible with ORY Oathkeeper v0.12.2+oes.7 and ORY Keto v0.6.0-sandbox+oes.7.
• ORY Hydra v1.0.3+oes.8 is probably not fully compatible with ORY Oathkeeper v0.12.1+oes.6 nor with ORY Keto v0.5.1-sandbox+oes.6.
• ORY Hydra v1.1.0+oes.9 is best compatible with ORY Oathkeeper v1.1.0+oes.9 and ORY Keto v1.1.0+oes.9.

Important: Each release - unless explicitly labeled as -unstable - is going through extensive quality assurance and is considered secure and reliable enough to be run in production. If you choose to go with an incubating or sandbox service, it is likely that you will spend some time addressing breaking changes.

We always provide ways to migrate breaking changes, and all breaking changes are meticolously described in each project's UPGRADE.md as well as HISTORY.md.

[aeneasr]

Fixed