Template versioning

Flourish templates have a version number, which follows the format and semantics defined by the Semantic Versioning 2.0.0 specification. The version number may be specified in the template.yml file (which takes precedence), or in the package.json file if you have one.

When you publish a new version of a template, the new template will replace the old one or live alongside it, depending on whether your new version has the same major version number as the existing version. The practical implications of this are explained in more detail in the sections Publishing a compatible update and Publishing an incompatible update below.

When you publish a template, your new version must have a higher version number than any previously-published version that has the same major version number. Read on for details.

Transition from legacy unversioned templates

Support for versioned templates was introduced in version 3.7.0 of the Flourish SDK, released in January 2019. Prior to that release, Flourish did not record the version numbers of templates, even if your template had a version number specified in its package.json file.

First make sure your template has a version number. If your template is packaged as a Node module, it probably already has a version number specified in package.json. Check that this is the version number you want. If your template is not packaged as a Node module, or if for some reason you want to use a different version number in Flourish, you should add a version field to the top level of your template.yml file.

Before you publish a template with a version number, using version 3.7.0 or later of the SDK, you should tell Flourish to record the version number of the currently published version, using the command flourish assign-version-number. You can check whether your template has a version number in Flourish using the flourish list command with version 3.7.0 or later of the SDK. If the template has a version number, it will be printed next to the template id. For example:

$ flourish list circle
circle 1.0.0

If your template does not have a version number in Flourish, you should begin by assigning a version number to the already-published version using flourish assign-version-number.

How to tell if your new version is backwards-compatible

Roughly speaking, a new version is backwards-compatible if existing visualisations will continue to work as well or better with the new template. Adding a new (optional) feature will usually be a backwards-compatible change – occasioning a bump to the minor version number – whereas removing a feature will usually not be.

In some cases one might change a template in a way that has no user-visible effect on new visualisations, but is nevertheless not compatible with existing visualisations. Changing the name of a setting property or a data binding key are examples of changes of this sort. In this case, you should bump the major version number.

If you want to test whether a new version of a template is indeed compatible with existing visualisations, it is possible to do that in a rather roundabout way. Suppose the live version of the template is 1.2.3, and you plan to publish version 1.3.0, but you would like to make sure that it will work correctly with visualisations that were created using the old version of the template. You can do that as follows:

  1. Check out the old version (1.2.3) of the template from your version control system.
  2. Edit its version number in package.json or template.yml, and change it to 1.3.0-prerelease.1.
  3. Publish the template to Flourish.
  4. Create a visualisation in Flourish using the version of the template you just published.
  5. Check out the new version (1.3.0).
  6. Change its version number to 1.3.0-prerelease.2.
  7. Publish it to Flourish.
  8. The visualisation you created earlier will have been moved to the newly-published template. Open it in the Flourish visualisation editor, verify that it works as expected, and check your browser’s developer console to make sure the template is not throwing any errors.

We plan to make this easier in the future.

Publishing a compatible update

If your new version is backwards-compatible, so has the same major version number as the old one, existing visualisations will automatically be moved to the new template. The next time such a visualisation is opened in the Flourish visualisation editor, it will use the new version.

Published visualisations are not affected by template republication under any circumstances, and will use the version that was current when they were published forever, or until they are republished.

Publishing an incompatible update

If your new version is not compatible with the old one, and has a larger major version number, existing visualisations will continue to use the old version. Newly-created visualisations will use the new version.

Patching an old version

Consider the following scenario:

  • You publish version 1.2.3 of your template
  • Lots of visualisations are created using this version
  • You publish version 2.0.0. The existing visualisations using version 1.2.3 continue to use that version
  • You discover a serious bug in version 1 of the template

In this situation, you may want to publish version 1.2.4 fixing the bug, so that the existing visualisations using version 1.2.3 can benefit from the fix.

Prerelease versions

When you have developed a new version of a template, you may want to test it on Flourish before releasing it for general use. You can do this by adding a prerelease tag to the version number before you publish it. For example, if you are preparing version 1.3.0 of a template, you can set the version number to 1.3.0-alpha.1 before you publish it.

This has the effect that existing visualisations are not automatically moved to the new version, but you can explicitly create visualisations against it from the template page. The URL of this page is printed to your terminal by the flourish publish command when the template has been published.

You can publish later prerelease versions 1.3.0-alpha.2, 1.3.0-alpha.3, and so on. See section 9 of the Semantic Versioning 2.0 specification for full details of the structure of these prerelease tags, and section 11 for how to tell when one version is newer than another.

When you are happy with the new version, change the version number to 1.3.0 – with no prerelease tag – and publish again. Any visualisations you created against your prerelease versions will be moved to the newly published version, as well as any visualisations created against the previously-live version 1 of the template.

Bumping the version number when publishing

The flourish publish command has some options that may be convenient in some situations.

  • If you have made a minor patch fix to a template, and you are sure it works, you can use flourish publish --patch, which automatically increments the patch number in your template.yml or package.json file before publishing the template.
  • If you have made a minor patch fix to a template, and you want to check that it works on Flourish, you can use flourish publish --prerelease, which publishes a prerelease version. In detail, it does the following:
    • If your current version number has a prerelease tag that ends with a numeric part, the value of the numeric part is incremented.
    • If your current version number has a prerelease tag that does not end with a numeric part, a numeric part is appended with value 1. For example 1.2.0-alpha becomes 1.2.0-alpha.1.
    • If your current version does not have a prerelease tag, the patch number is incremented and the tag -prerelease.1 is appended.
  • To remove the prerelease tag and then publish the template, you can use flourish publish --release.