Releases

Versioning

Platform

The platform uses a calendar versioning system with two major releases a year. Its format is year.major.release. Major releases include deprecations and breaking changes, whereas other releases introduce backwards compatible new features, bug fixes, or internal improvements.

Plugin

NPL-Dev plugin releases use +platform.version to indicate the platform versions they were built against (and are therefore compatible with).

Upgrading releases

For the best experience, it is typically recommended to use the latest version of the Noumena Platform.

An overview of platform versions and corresponding release notes can be found here. Deprecations are documented here.

Major releases

When upgrading to a major release, take the following steps:

1. Ensure there are no NPL deprecation warnings on the release you're currently running. If there are, update the NPL and apply migrations.
2. Ensure there are no Environment Variable deprecation warnings on the release you're currently running. If there are, update the deployment files first.
3. Follow the upgrade instructions for the major version.

Release candidates

Between the official releases, the platform publishes release candidates. Release candidates are purged when the official releases are published. Therefore, they should never be used in a production system.

In order to test using a release candidate, you must first indicate that the application is running in a development mode. This is done by setting the ENGINE_DEV_MODE environment variable to true for the engine application and the HISTORY_DEV_MODE environment variable to true for the history application.

To ensure that the two applications work as expected, it is recommended that the two environment variable values match.

After successful testing, change the version to the candidate version that you want to test with (also, reset the _DEV_MODE environment variable values) and restart the applications.

Downgrading

Forward compatibility of older versions is not guaranteed. Version downgrades, such as moving a system on version 2021.1.3 to version 2021.1.2, are therefore actively checked for and explicitly forbidden.

The last version used in a particular environment is stored in the database. While certainly not recommended, it can under extreme circumstances be manually overridden.

Feature flags

Feature flags allow the end-user to have a delayed adoption for the feature or change related to the flag. Functionalities that would otherwise be breaking changes can be wrapped in feature flags so that they can be enabled/disabled. Breaking features are enabled by default. This means that the new (breaking) behavior will be active unless intentionally de-activated by disabling the specific feature flag. When 'disabled', the feature will have identical behavior as it did previously.

Example

Assume a new breaking change where NPL suddenly requires line numbers. If you upgrade your engine, your current NPL will no longer work. In this case, the platform would provide a feature flag like FEATURE_LINE_NUMBERS_REQUIRED which can be set to false to maintain the old behavior until all your NPL has been updated.

In this way we can support new features and be backwards compatible until such time as we no longer support the previous behavior.

Each feature flag will have the following lifecycle.

1. Feature functionality is introduced along with its feature flag.
2. Ongoing support per license agreement but deprecation warnings will be added where possible.
3. At end of life, all support will end and previous functionality will be removed.

You can set the desired value using respective environment variables, prefixed with FEATURE_% (listed in the configuration reference, e.g. engine feature flags).