Versioning

A released version in Clarify has the syntax MAJOR.MINOR.PATCH. For each MAJOR.MINOR combination, only the latest PATCH release is selectable, using a selector string of "MAJOR.MINOR".

A pre-release version in Clarify has the syntax MAJOR.MINOR.PATCH-IDENTIFIER. Where the identifier is either of syntax beta.N or beta.N.M. In practice, pre-releases only makes sense to do when incrementing either the MINOR or the MAJOR number, hence the typical version selector string will be "MAJOR.MINORbetaN".

The versions selection string is supplied as an HTTP header.

A version selector string maps to the latest PATCH or beta.N.M release.

Semanic versioning

For documentation purposes, the full version string of the Clarfy API is following the rules of Semantic Versioning, which means that we use the version number to document backwards compatibility:

• An increment of the MAJOR version indicates breaking changes to the API.
• An increment of the MINOR version indicates new backwards-compatible features.
• An increment of the PATCH version indicates noticable bug fixes or backwards compatible changes to limts, field validation, etc.

Because we are writing a JSON API that needs to work with multipe programing languages, we define backwards compatibility in a particular way which you can read more about in our "Backwards compatibility promise" below.

Backwards compatibility promise

Use explicit version selection to mitigate risks

While we recommend all code to use explicit version selection, it is particular important for code that rely on positional RPC parameters, or have JSON parser implementations that are sensitive to the presence of unknown fields.

This promise is to be viewed as a promise of intent, and not a legally binding agreement. Still, we will do what we can to uphold this promise to the best of our ability.

All versions 1.X.Y should retain backwards compatible with all previous versions 1.X.Y, except for the cases listed below:

• If a feature is completely removed from Clarify, we may be forced to remove functionality in all MAJOR.MINOR versions of the API. The threshold for doing this should be considered high, but if it happens, we will explicitly allow for breaking changes to occur in both MINOR and PATCH releases as a means of documenting feature removal.
• If a serious security concern require that we introduce breaking changes to the API, we will explicitly allow it to occur in both MINOR and PATCH releases.

We define the follwing changes to be backwards compatible:

• Add new optional parameters to exisisting methods.
• Change the order of existing JSON RPC method parameters.
• Change the order of properties/fileds in any JSON object in the response.
• Add new peopertie/fields to any JSON object in the response.
• Add new error codes.

To aid any clients tht are sensitive to the issues above, we will avoid doing the follwing changes as part of a PATCH releass:

• Change the order of existing JSON RPC method parameters.
• Add new peopertie/fields to any JSON object in the response result.

Using pre-releases

Use at your own risk

Pre-releases can be potentially unstable, and will eventually be reomved. All usage happens at your own risk, and we offer no gurantees for how long the pre-release will remain available, or that breakig changes won't occur for any given version selection string.

In Clarify, the format of a pre-release identifier suffix is either -beta.N or -beta.N.M. Here we use the N.M numbers to indicate intended backwards compatibiliy:

• An increment of the N number indicates breaking changes to the API.
• An increment of the M number indicates new features that are intended but not guranteed to be backwards-compatible.

Breaking changes should also be expected between a pre-release and the final MAJOR.MINOR.PATCH release.

Bug fixes for pre-releases may be done withot any additional cermony or documentation effort. A feature is considered added when it first gets documented, and not when it's first made available in the pre-release API.