App versioning allows you to easily add or change your app's functionality without disrupting existing users. It allows you to maintain multiple draft versions of your app and push them to users as you finish features to ensure they have access to the latest and greatest features.

Types of versions

You can create a major and minor version, depending on the type of changes you want to make.

Minor versions are for small, non-breaking changes that can immediately be pushed to users. They will automatically be added to existing users' accounts.

Major versions are for large changes that could potentially break a user’s workflow. These types of changes typically require user approval or reconfiguration. Major version releases require existing users to manually update their app. Keep in mind that automations will not automatically update to avoid breaking changes when you release a new major version. Users will need to remove the automation and add it again.

While you can make most configuration changes with a minor version, the following require a major version:

• Changing app's permission scopes
• Changing your app name
• Changing your app's OAuth configuration

Since minor versions are pushed automatically, they can have a large impact on users. If you don't know whether or not your change will break existing workflows, we recommend using a major version to be safe. No matter which type of version you ultimately decide to release, new users will always install the latest version of your app!

When to use a major or minor version

Here are a few scenarios and our recommendations for what kind of version to use. These are generalized guidelines that won’t cover every scenario, so please use your own judgment to minimize user impact.

Adding a new feature to your app

If you’re adding a completely new feature to your app that won’t affect any existing users’ workflows, use a minor version.

Changing the URLs in your app

For invisible changes in your app’s backend, use a minor version. Make sure you thoroughly test the app as any bugs will be pushed directly to all users!

Adding a new recipe to an integration

If you’re adding a new recipe to an existing integration feature, use a minor change. New recipes don't impact any other recipes in the feature, so you do not need to create a major version.

Changing the logic of an existing integration recipe

If you’re changing an existing integration recipe, existing recipes will break. Therefore, use a major version for this. Alternatively, you can create a new recipe and push it as a minor change (this approach will add clutter to your app as you have more and more recipes).

Adding additional configuration to an existing integration recipe

Adding new fields to existing recipes will break them for current users, so you should use a major version.

Removing an existing integration recipe

Completely removing a recipe will break it for current users, so you should use a major version.

Small UI changes in board views or widgets

If the UI of your view or widget changes slightly, you can make this change in a minor version.

Changing settings in board views or widgets

Adding an optional settings field to configure your view or widget is generally a non-breaking change, so many times you can just create a minor version. Use your discretion here and make it a major version if the new setting is required for the app to work.

Overhauling a view or widget

If you completely change the functionality of an existing widget, use a major version. If you want a more seamless experience for your users, you can add the view as a new feature and remove the old one in a minor version.

Patching a bug from a previous version

If a version has broken something for your users: create a new minor version, fix the issue, and then promote it to patch the bug for all existing users.

Managing versions

You can manage your app's versions in the App Versions pane in the Developer's section.

Creating a version

1. Navigate to the App Versions tab.
2. Click New Version.
3. Select Major Version or Minor Version.
4. Press the blue Create Version button.

The version number will be based on the most recent version of your app. If your app's live version is 1.4 but the highest version in your drafts is 3.0, the new version number will be 3.1.0 (minor) or 4.0.0 (major).

Every new version will default to a Draft status, and all configuration will be copied from the current live version.

❗️

NOTE

You can't create a new major version if you already have one in your drafts.

Promoting a draft version to live

When you’ve finished working on your draft and want to release it to your users, click the three dot menu on the far right and select Promote to live. Your new version will now be available to your users.

For minor changes, users will automatically have access to the new version. For major versions, users will need to manually update their app or they won't have access to the new version until they do so. If a feature was removed from the most recent version of your app, for example an integration recipe, it will not be removed from your users’ boards. Instead, it will show as read-only for those users.

Deleting a draft

If you want to delete a draft to keep your app organized, click the three dot menu and select Delete this version. To ensure continuity for your users, you cannot delete live or deprecated versions.

Supporting past versions

When you release a new major version of your app, the majority of your user base will still be using the old version. Slowly they will move to the new version, but there will probably always be some portion of your user base spread over old versions.

As a result, your app’s backend must support the logic of your old versions. This could mean having endpoints to support old integration recipes or fallback logic in your app’s code if a particular setting or field doesn’t exist. Generally speaking, you should build your backend to support all previous versions of your app.

If you decide to fully deprecate an old version, you can send the user a notification or show them to a splash screen that advises them to reinstall the app’s newest version.

The versioning process

Check out this simple example that walks through the app versioning process!

1. You have a brilliant idea for a new app, so you start developing it.
2. When you’re ready to share your app with the world, you publish it.
3. Due to some changes in your server configuration, you need to change some of your app's endpoints. You create a new minor version (1.1.0) and make the changes you need.
4. When you’ve completed the changes and are ready to push them to your users, you promote version 1.1.0. Your existing users will be automatically migrated to the new version.
5. Now you have an idea for an awesome new feature for your app that will revolutionize your users’ experience. You create a new major version (2.0.0) for these changes.
6. Once you’re ready to push these changes to your users, you promote version 2.0.0 to the live version. New users who install your app will now get this version of your app. Existing users will need to manually update their app before they can use it.

❗️

NOTE

Versioning does not apply to the permissions or authorization configuration of your app (such as Authentication scopes and OAuth URLs). Draft versions will always take the scopes and OAuth configuration from the live version of your app.