App versioning

12 min

Optimizely Connect Platform (OCP) uses the following format for app versioning: <app_name>@<app_version>. Where <app_version> consists of the version number and pre-release tag.

For example, if your app name is my_new_marketing_app, your app version is 0.0.0, and you are currently testing the first iteration of your pre-release dev app, your app's version format would look like, [email protected].

Version number

OCP apps use the following Semantic Versioning (SemVer) specification. Given a version number MAJOR.MINOR.PATCH, increment

the MAJOR version when you make an incompatible API change.

the MINOR version when you add functionality in a backward-compatible manner.

the PATCH version when you make backward-compatible bug fixes.

Note

When you update your app version, make sure you update all external API call headers.

Upgrading from one MINOR version to another is performed automatically when the new app version is published. For example, if you have published app version 1.0.0 and then publish 1.0.1, the functions onUpgrade and onFinalizeUpgrade in the Lifecycle.ts file are executed automatically for every install on every client account.

However, upgrading from one MAJOR version to another is not performed automatically when the new app version is published. For example, if you have published app version 1.0.0 and then publish 2.0.0, the functions onUpgrade and onFinalizeUpgrade in the Lifecycle.ts file are executed when the client end-user manually clicks Upgrade in the OCP App Directory UI.

Pre-release tag

OCP uses the following pre-release tag, which releases your app to only your private production account.

-dev – Versions with a -dev tag are intended for internal testing of your apps, are limited to running in your associated OCP account, are not shareable, and let you bypass the app review process.

Any app with the -dev pre-release tag is not globally visible inside the App Directory and is intended to serve as a work in progress.

Pre-release versioning

Pre-release versioning lets you work on a single train of code that is consistently named MAJOR.MINOR.PATCH, where you increment the pre-release tag as necessary until you are ready for your production release.

For example, imagine your next OCP app release is 2.1.9. During your development work, you end up with four pre-release dev versions before you are ready for the final release. Your versioning would look like this:

2.1.9-dev.1 – Your first pre-release version

2.1.9_dev.2 – Your second pre-release version

2.1.9_dev.3 – Your third pre-release version

2.1.9_dev.4 – Your fourth pre-release version

2.1.9 – Your release version

The pre-release tag and versioning lets you modify your release without incrementing the MAJOR, MINOR, or PATCH numbers. That way, your release version remains consistent while you work on your code, only incrementing the pre-release tag as you work.

Update your pre-release app version

To update your pre-release dev app version:

Update the version field in the app.yml file for your app on your local machine. Increment the pre-release dev version by 1 and save your changes. For example, if your current pre-release dev version is 0.0.0-dev.1, update it to 0.0.0-dev.2.

Run the following command in the OCP CLI to validate, package, upload, and build your pre-release dev app version:

opti app prepare <path>

Publish your pre-release dev app version. In this example, <appVersion> is [email protected]:

opti directory publish <appVersion>

Your app running in your personal OCP production account is automatically upgraded to the new app version. You can see this by navigating to the App Directory and clicking the app tile. The current version of your app displays:

Preview track versions

Experimental

Preview tracks are experimental.

Instead of bumping a pre-release tag for each iteration, deploy an app to a preview track, such as dev/jdoe or beta/feature-x. A preview version is identified by TRACK/SHA, such as dev/jdoe/abc1234, where SHA is a seven-character hash of your app content. Deploying to a track builds and publishes in one command:

ocp app deploy

Preview tracks replace the -dev and -beta pre-release versions you use while you build an app. Use the semantic versioning described on this page to release an app:

Preview versions – OCP never reviews them. Accounts install them only by following their track, and the OCP App Directory lists them only for those accounts.

Semver versions – They keep the behavior described on this page, including the review process and auto-upgrade ordering. Releases use them.

While the feature is experimental, preview tracks and pre-release versions both work for the same app at the same time. Existing -dev, -beta, and -private versions and their installations continue to work. You cannot create versions with those tags through ocp app deploy.

See Deploy apps with preview tracks for details.

General availability (GA) release versioning

When you are finished testing your app and are ready to release it to GA, you enter the app review process. Your app is approved as a beta app, private app, or released app:

Beta apps – Use the -beta release tag to release your app as a beta. Versions with a -beta suffix can only be installed using an app beta share link (for example, https://get.optimizely.app/{{app}}?v=1.0.0-beta).

Private apps – Apps that are released to production, but their availability in the OCP App Directory is limited to one or more accounts.

Released apps – Apps released to production are generally and publicly available in the OCP App Directory.

Update your GA app version

To update your app version and publish to production:

Update the version field in the app.yml file for your app on your local machine. Remove the pre-release tag and save your changes. For example, if your current pre-release dev version is 0.0.0-dev.1, update it to 0.0.0.

Run the following command in the OCP CLI to validate, package, upload, and build your production app version:

opti app prepare <path>

Publish your production app version. In this example, <appVersion> is [email protected]:

opti directory publish <appVersion>

Your app running in your personal OCP production account is automatically upgraded to the new app version. You can see this by navigating to the App Directory and clicking the app tile.

Examples of valid app versions:

1.0.0
0.0.1-dev.1
1.0.0-beta.2
1.2.3-private

Example of invalid app versions:

Version	Reason
1.0	The version number only includes a MAJOR and MINOR number, but is missing the required PATCH number.
1.2.3.4	The version number includes four numbers separated by periods, which is not a valid semantic version.
1.002.3	The MINOR number has a leading zero.
1.2.3-dev.01	The pre-release tag has a leading zero.
1.2.3-internal	The pre-release tag is invalid; only dev, beta, and private are supported.
1.2.3-	The version number includes a hyphen followed by nothing, which is not a valid pre-release identifier.
1.2.3-beta-2	The pre-release version is followed by a hyphen instead of a dot.

Version limits

OCP limits how many semver versions of an app run at the same time. The limits count running versions only. A version that is built but not started, or one that is stopped, does not count. Unpublish a version with ocp directory unpublish YOUR_APP_ID@VERSION to free its slot.

The following limits apply:

MAJOR versions per app – two

MINOR versions per MAJOR version – three

-dev versions per app – five

-beta versions per app – five

-private versions per app – two

A publish that exceeds a limit fails with a message that names the limit, such as Deployment would exceed limit of 2 major versions for app my_app. Unpublish an unused version, then publish again.

Preview track versions do not count against these limits, and they have their own naming rules, including the 32-character version identifier. See Preview track limits.