Versioning your template
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 on 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 v3.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 visualizations 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 visualizations, but is nevertheless not compatible with existing visualizations. 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 visualizations, 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 visualizations that were created using the old version of the template. You can do that as follows:
- Check out the old version (1.2.3) of the template from your version control system.
- Edit its version number in package.json or template.yml, and change it to
1.3.0-prerelease.1
. - Publish the template to Flourish.
- Create a visualization in Flourish using the version of the template you just published.
- Check out the new version (1.3.0).
- Change its version number to
1.3.0-prerelease.2
. - Publish it to Flourish.
- The visualization you created earlier will have been moved to the newly-published template. Open it in the Flourish visualization 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 visualizations will automatically be moved to the new template. The next time such a visualization is opened in the Flourish visualization editor, it will use the new version.
Published visualizations 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 backwards-compatible, and has a larger major version number, existing visualizations will continue to use the old version (as will any duplicates that are made of existing visualizations using this old version). Newly-created visualizations will use the new version.
Patching an old version
Consider the following scenario:
- You publish version
1.2.3
of your template - Lots of visualizations are created using this version
- You publish version
2.0.0
. The existing visualizations using version1.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 visualizations 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 in 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 visualizations are not automatically moved to the new version, but you can explicitly create visualizations 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 visualizations you created against your prerelease versions will be moved to the newly published version, as well as any visualizations 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 example1.2.0-alpha
becomes1.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
.