Release handling and versioning

Versioning

Semantic Versioning is a standard for versioning and numbering software releases. Each release is assigned a three-component version number in the format X.Y.Z, where:

X – Major version The major version is incremented when major changes or new functionality are introduced. Backward compatibility is not guaranteed, and breaking changes should be expected.
Y – Minor version The minor version is incremented when new, minor functionality is introduced. Backward compatibility should largely be retained; however, unforeseen breaking changes may occur in rare cases.
Z – Patch version The patch version is incremented when very minor functionality is introduced or when bug fixes are implemented. Backward compatibility will be retained as far as possible, though unforeseen breaking changes may occur in very rare cases.

Information about new versions

Major changes

Information about major changes that result in a new major version will be communicated no later than three (3) months prior to release. Communication will be made via email and published in the API documentation in connection with the release. When releasing new major versions, the deprecation period may vary depending on the nature of the release, as described below.

Scenario 1 The current version stops working immediately upon release of the new version. This scenario is unlikely but may occur, for example, if changes to authentication are required. In this case, the deprecation period for the current version will consist of the time between the first communication and the release date.

o Example 1 Version 2.0.0 is released on 1 December, and the first communication is sent on 31 August. The deprecation period for version 1 is 31 August – 30 November. On 1 December, version 1 is closed.

o Example 2 Version 2.0.0 is released on 1 January, and the first communication is sent on 31 August. The deprecation period for version 1 is 31 August – 31 December. On 1 January, version 1 is closed.
Scenario 2 The new version runs in parallel with the previous version for all supported endpoints. This scenario may occur if, for example, the representation of an object is changed (such as naming or number of parameters, but not the underlying data) in the Next Project API.

In this case, the deprecation period for the current version will be determined by whichever of the following occurs first:
- The period between the first communication and the release date plus three (3) months, or
- The date of the next major release.
o Example 1 Version 2.0.0 is released on 1 September, and the first communication is sent in connection with the release. The deprecation period for version 1 is 1 September – 30 November.

o Example 2 Version 2.0.0 is released on 1 December, and the first communication is sent on 31 August. The deprecation period for version 1 may be set as: • Fixed date: 31 August – 30 November • Flexible date: 31 August – no later than 28 February, or until the release of version 3, whichever occurs first.
Scenario 3 The new version introduces breaking changes for only a subset of the API. In this scenario, only integrations that rely on the affected functionality will be impacted. This may occur if endpoints or fields are removed or renamed, data types are changed, or underlying background services are modified.

Urgent changes

Urgent changes that result in a new major version (for example, to address serious security issues) will be released as soon as possible. Such changes will be communicated via email and documented in the API documentation. We will strive to provide advance notice prior to release whenever possible; however, there may be situations where prior communication is not feasible.

Minor changes

Information about minor changes that result in a new minor version will be communicated no later than in connection with the release. Communication will be made via email and published in the API documentation.