Versioning and migration

New in version 1.10.

If you intend to distribute your workflow, it’s a good idea to use version numbers. It allows users to see if they’re using an out-of-date version, and more importantly, it allows you to know which version a user has when they ask you for support or to fix a bug (that you may already have fixed).

If your workflow has a version number set (see Setting a version number), the version will be logged every time the workflow is run to help with debugging, and can also be displayed using the workflow:version magic argument.

If you wish to use the self-updating feature, your workflow must have a version number.

Having a version number also enables the first run/migration functionality. See First run/migration below for details.

Setting a version number

There are two ways to set a version number. The simplest and best is to create a version file in the root directory of your workflow (next to info.plist) that contains the version number:

Your Workflow/
        icon.png
        info.plist
        yourscript.py
        version
        workflow/
                ...

You may also specify the version number using the version key in the update_settings dictionary passed to Workflow, though you can only use this method if your workflow supports self-updates from GitHub.

Using a version file is preferable as then you only need to maintain the version number in one place.

Version numbers

In version 1.10 and above, Alfred-PyWorkflow requires Semantic versioning, which is the format GitHub also expects. Alfred-PyWorkflow deviates from the semantic versioning standard slightly, most notably in that you don’t have to specify a minor or patch version, i.e. 1.0 is fine, as is simply 1 (the standard requires these to both be written 1.0.0). See Semantic versioning for more details on version formatting.

The de-facto way to tag releases on GitHub is use a semantic version number preceded by v, e.g. v1.0, v2.3.1 etc., whereas the de-facto way to version Python libraries is to do the same, but without the preceding v, e.g. 1.0, 2.3.1 etc.

As a result, Alfred-PyWorkflow will strip a preceding v from both local and remote versions (i.e. you can specify 1.0 or v1.0 in either or both of your Python code and GitHub releases).

When this is done, if the latest GitHub version is higher than the local version, Alfred-PyWorkflow will consider the remote version to be an update.

Thus, calling Workflow with update_settings={'version': '1.2', ...} or update_settings={'version': 'v1.2', ...} will be considered the same version as the GitHub release tag v1.2 or 1.2 (or indeed 1.2.0).

Semantic versioning

Semantic versioning is a standard for formatting software version numbers.

Essentially, a version number must consist of a major version number, a minor version number and a patch version number separated by dots, e.g. 1.0.1, 2.10.3 etc. You should increase the patch version when you fix bugs, the minor version when you add new features and the major version if you change the API.

You may also add additional pre-release version info to the end of the version number, preceded by a hyphen (-), e.g. 2.0.0-rc.1 or 2.0.0-beta. Note that Alfred-PyWorkflow does not use this pre-release version format to identify pre-releases; instead the pre-release option on the GitHub release editing page must be selected for releases that are not production-ready.

Alfred-PyWorkflow differs from the standard in that you aren’t required to specify a minor or patch version, i.e. 1.0 is fine, as is 1 (and both are considered equal and also equal to 1.0.0).

This change was made as relatively few workflow authors use patch versions.

See the semantic versioning website for full details of the standard and the rationale behind it.

First run/migration

New in version 1.10.

If your workflow uses version numbers, you can use the Workflow.first_run and Workflow.last_version_run attributes to bootstrap newly-installed workflows or to migrate data from an older version.

first_run will be True if this version of the workflow has never run before. If an older version has previously run, last_version_run will contain the version of that workflow.

Both last_version_run and version are Version instances (or None) to make comparison easy. Be sure to check for None before comparing them: comparing Version and None will raise a ValueError.

last_version_run is set to the value of the currently running workflow if it runs successfully without raising an exception.

Important

last_version_run will only be set automatically if you run your workflow via Workflow.run(). This is because Workflow is often used as a utility class by other workflow scripts, and you don’t want your background update script to confuse things by setting the wrong version.

If you want to set last_version_run yourself, use set_last_version().