Versioning in your apps
Read this guide to learn how to use versioning to manage different releases of your apps.
What is versioning?
App versioning allows you to add or change functionality of your app easily without disrupting existing users.
When you create your app, it will default to version 1.0.0. As you add new features and change the functionality of your app, you should create new versions and promote them to give them the latest and greatest features of your app.
At a high-level, versioning allows you to maintain multiple draft versions of your app and push them to your user base as you finish features. Minor versions will be automatically pushed to your users, and major versions will require users to reinstall the app in the admin section.
You can change versions in the dropdown at the top left of the main app page:
Tip: We recommend using minor versions for small changes to your app, and major versions for any changes that could break your users’ workflows.
The versioning process
Here is a simple example to demonstrate the app versioning process. Before diving into versioning, we recommend reading this article to understand the basics of app management.
- You have a brilliant idea for a new app. You create the app and start developing it.
- When you’re ready to share your app with the world, you publish it. (Don’t know how to publish an app? Read this article.)
- Due to some changes in your server configuration, you need to change some of the endpoints for your app. You create a new minor version (1.1.0) and make the changes you need.
- When you’ve completed the changes and are ready to push them to your users, you promote version 1.1.0 (we’ll go over version promotion later). Your existing users will be automatically migrated to the new version.
- 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.
- 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 reinstall the app in the admin section before they can use it.
Note: The changes described in this example are only for demonstration purposes. For recommendations of when to use minor/major versions, check out the section later in the article.
You can manage your app's versions in the “App Versions” pane inside your apps configuration:
Creating a version
To create a new version, open the versions screen and click “new version”.
Now, select if your version will be a major or minor version. Click “Create version” to create the version. By default, the status will be “Draft”. All configuration will be copied from the current live version.
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).
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.
Note: if you promote a major version to live, your users will need to reinstall the app.
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.
Types of versions
There are two types of version you can create – major and minor.
Major versions are for large changes that could potentially break a user’s workflow. Existing users will need to reinstall the app when a new major version is released.
Minor versions are for small changes that can be pushed to users immediately. When you promote a minor version it will automatically be added to existing users’ accounts.
New users will always install the latest version of your app, regardless of the version type.
Note: Promoting minor versions can have a large impact on users, since they are pushed automatically. If you're unsure if a change will break existing instances, use a major version just in case.
Changes that require a major version
While you can make most changes in configuration with a minor version, there are a few that require a major version. These are:
- Changing app's permission scopes
- Changing your app name
What will my users see when I promote a version to live?
This depends on if your version update was a major or minor change. For minor changes, users will be transferred to the new version automatically.
For major versions, they will need to reinstall the app. They can do this from any of the widget/view centers.
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.
When should I 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: minor version
If you’re adding a completely new feature (view, widget, integration) to your app, it won’t affect any existing users’ workflows. Therefore, use a minor version.
Changing the URLs in your app: minor version
For invisible changes in your app’s backend, use a minor version. Make sure you test the app well, because any bugs will be pushed directly to all users!
Adding a new recipe to an integration: minor
If you’re adding a new recipe to an existing integration feature, use a minor change. This is because adding a new recipe does not affect any of the other recipes in the feature.
Changing the logic of an existing integration recipe: major
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: major
Adding new fields to existing recipes will break them for current users. Therefore, use a major version.
Removing an existing integration recipe: major
Completely removing a recipe will break it for current users. Therefore, use a major version.
Small UI changes in board views or widgets: minor
If your view or widget changes slightly in UI, you can make this a minor change (non-breaking change).
Changing settings in board views or widgets: minor or major
Adding an optional settings field to configure your view or widget is generally a non-breaking change. 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: major
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, remove the old one, and use a minor version.
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.
Help! I promoted a version that broke my app!
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.