Versioning your Transposit application

You can now easily version your Transposit applications and control which version, also known as a tag, is deployed. Full docs are here, but in this post I'm going to examine why you might want to enable versioning, what is versioned and how you can switch between versions.

Why version#

If you aren't using versions, Transposit has two execution environments. There's the development environment (what you see when you navigate to Code > Development). This code is executed when you click the 'Run' button after typing in the code editor.

Then there is the production environment. The code in the production environment is what scheduled tasks run, what your users will see, and what is exposed via your deployed endpoints. Once you've commited code in the console, you've implicitly pushed it to this production environment. If you pull down your application repository via git clone and make a change and push it up, that committed code is also in production.

When you are first developing your application, you can rest assured no users will be affected if you commit broken code. Whether a typo, a bug in your logic or a new function, no one is really exercising your code, even though the committed code is promoted to production.

However, once you have users, you want to be a bit more careful about changes. You can make changes in the development environment without affecting production, but what if you want to commit a smaller piece of work? Or commit at the end of the day? Your development code is automatically promoted to the production environment. You can work around this by doing new development in new operations (which won't be called) or commenting out your new changes before committing, but these are both fragile error-prone workarounds.

Versioning walls off the production environment and isolates it to run just the deployed version. It lets you create a known working application, run it in the production environment for your end users, and yet continue to develop other features or bugfixes as you wish.

What is versioned#

Only the items in your application repository are versioned. This includes code and metadata such as parameter definitions and operation descriptions. If you can pull it down from your application repository and edit it, it's versioned. Everything else is unversioned.

Some of the items that are unversioned:

• authentication keys, whether production or per user
• scheduled task definitions
• user settings and environment variables
• endpoint deployment and authentication settings
• stash keys and values

Creating a version#

This is as simple as clicking on the 'commit code' button and entering a version value such as v1.0.1. This will tags everything that is versionable. Again, more in the docs.

Note if you don't create a version, then Transposit falls back to the latest code that has been committed.

How to switch between versions#

You can switch between versions by navigating to Deploy > Endpoints. There you can choose which version of your code you want to deploy. Once you deploy a version, all future requests to endpoints will execute the newly deployed version. All scheduled tasks beginning after the deployment will execute the new code as well. But any requests or tasks in progress will complete against the previously deployed version.

Rolling back is as simple as changing the deployed version.

There is no requirement that versions move only forward. If you add a v1.0.1 version and then make a change and wish to commit the new version as v0.1.1, Transposit will allow you to do so.

Limits on versions#

In the console#

Versions apply a git tag to the application repository. However, Transposit imposes some additional constraints. Within the console, only versions that are in SemVer format are allowed: v1.0.1 and v0.0.1 are both valid versions, but 1.01 and REL_20191101 are not.

You must commit a change to add a version tag in the console. Each set of versions is tied to a given application--there is no relation between versions across different applications in your account. You must switch which version is deployed using the console user interface.

You cannot re-use versions or move a version when adding a version in the console.

Using the command line#

If you check out your application repository, you are free from some of the constraints of the console. (Note that with great power comes great responsibility.) There are still some limits, but you can use tags as you would in a non Transposit git repository.

However, if you add a tag that doesn't conform to SemVer format, the push will be rejected.

$ git tag REL_20191104
$ git push --tags origin master
Total 0 (delta 0), reused 0 (delta 0)
To https://console.transposit.com/git/xxx/yyy
 ! [remote rejected] REL_20191104 -> REL_20191104 (tag REL_20191104 does not conform to the SemVer format. Version syntax: v[major].[minor].[patch])
error: failed to push some refs to 'https://console.transposit.com/git/xxx/yyy'

You can remove versions. In general this should be done rarely, as the carrying cost of a version is extremely low (the same as a git tag), but if you erroneously add a version you could remove it: git tag -d v0.0.1 && git push --delete origin v0.0.1 You can also migrate a version to different set of code by removing the tag, updating the code and re-adding the tag.

Handling application changes#

Unversioned items are 'universal' and are shared across versions of your application. This means that you need to make sure any changes you make to these are compatible with any versions of your code that you are running. This can most easily be accomplished by adding new settings and marking old settings as deprecated. Then, in a while, you can remove the deprecated settings.

If you have a enviroment variable pointing to a dynamodb table (orders_table) and the application later switches to storing orders in S3, you can add a 'deprecated' notice to the orders_table environment variable description and file a bug to remove it in a few months. Then, before you remove it, you should review your source code to make sure that the orders_table variable isn't referenced by any versions which are or will be deployed.

This script should output nothing if it is safe to remove the orders_table environment variable:

for v in `git tag --list`; do
  git checkout $v
  grep -Rl orders_table src
done

Conclusion#

Versioning allows you to provide a stable environment for users of your Transposit application, whether they be other applications consuming an API or users interacting with a Slackbot. At the same time, you can be fixing bugs and improving functionality in an isolated environment. When your new code is ready, deploying is as easy as selecting the correct version and clicking save.