App versioning allows you to easily add or change your app's functionality without disrupting existing users. It enables 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 either a major or minor version, depending on the changes you want to make. Users will automatically have access to new minor versions, but major versions require them to update the app manually. No matter which type of version you ultimately decide to release, new users will always install the latest version!

Minor version

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

Since minor versions are pushed automatically, they can significantly impact users. If you don't know whether or not your change will break existing workflows, we recommend using a major version to be safe.

Major version

Major versions are for significant changes that could potentially break a user’s workflow. These types of changes typically require user approval or reconfiguration. You should use a major version for changes to your app name, OAuth configuration, and permissions scopes.

Major version releases require existing users to update their apps manually. Please note that automations will not automatically update to avoid breaking changes when you release a new major version, so users will need to remove the automation and add it again.

Which version should I create?

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

Adding a new feature to your app

Use a minor version if you're adding a new feature to your app that won't affect any existing users' workflows.
Changing the URLs in your app

For invisible changes in your app’s backend, use a minor version. Ensure you thoroughly test the app since any bugs will be pushed directly to all users!
Adding a new recipe to an integration
Use a minor version if you're adding a new recipe to an existing integration feature. New recipes don't impact 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 your view's or widget's UI 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 you can often create a minor version. Use your discretion here and make it a major version if the app requires the new setting 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 user experience, 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.

Sample app versioning scenario

Let's say you start developing a new app and publish it when you're ready to share your app with the world. 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 necessary changes. 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.

Now you have an idea for an excellent new feature for your app that will revolutionize your users’ experience. You create a new major version (2.0.0) for these changes. 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 update their app manually before they can use it.

Managing versions

You can create a new version, promote a draft version to live, or delete a draft version in your app's App Versions tab.

Creating a new version

You can create a new major or minor version when you need to make changes to your app. Versioning does not apply to your app's permissions or authorization configuration (such as Authentication scopes and OAuth URLs). Draft versions will always take the scopes and OAuth configuration from the current live version of your app.

The version number follows your app's most recent version (draft or live). 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). When you're ready to create a new version:

Navigate to the App Versions tab.
Click New Version.
Select Major Version or Minor Version. Please note that you can't create a new major version if you already have one in your drafts.
Press the blue Create Version button.
Your new version will be created and default to Draft status. You can now move on to the next section!

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-dots on the far right.
Select Publish.
Click Promote.
Users will automatically have access to new minor versions, but they need to update their app manually to access new major versions.

Deleting a draft version

The app version list can easily become cluttered after creating multiple versions, so you can delete draft versions to keep your app organized. To ensure continuity for your users, you cannot delete live or deprecated versions. Follow these quick steps to delete a draft version:

Click the three-dots on the far right.
Select Delete this version.
Click Delete.

Supporting past versions

When you release a new major version of your app, most 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 app versions.

If you fully deprecate an old version, you can send the user notifications or show them a screen prompting them to reinstall the app's newest version.

📘
Join our developer community!
We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎