Framework and Toolkit Versioning

🕐 4 min read

WDC 3.0 versioning considerations

There are several components of the Web Data Connector (WDC) 3.0 framework that are independently versioned and can affect the forward or backwards compatibility of connectors developed using the framework. Those components are:

• Tableau products: Tableau Desktop, Tableau Server, Tableau Prep, and so on
• taco-toolkit: CLI/tookit used to develop connectors
• .taco project and file: The connector development project and the resulting packaged connector itself

Based on the versioning of these components, there are some principles to keep in mind when developing connectors:

• The taco-toolkit version will always align with a particular Tableau product version.
• A connector project and resulting packaged connector (.taco) will have a minimum version of Tableau that it’s compatible with, depending on the version of taco-toolkit that it’s developed with.

Bug fixes and the addition of new features or capabilities to the WDC 3.0 framework might require an update to Tableau products, taco-toolkit, the connector, or all of them at once. From a developer perspective, updating a connector to apply a bug fix or new feature requires you to update taco-toolkit and your Tableau product version.

So, let’s say that a new WDC 3.0 capability is introduced in the latest version of Tableau and a corresponding new version of taco-toolkit is published. What do you do as a developer? There are several possibilities:

1. To use the new capability, implement the required connector code changes and rebuild your connector using the latest taco-toolkit. This makes the connector incompatible with versions of Tableau earlier than the minimum version specified by the toolkit.
   1. Update taco-toolkit (npm install the latest package)
   2. Run taco build on the existing project. This step will fail and inform you of elements in the connector that must be updated.
   3. Make any necessary code changes to the connector.
   4. Run taco build again to ensure success.
   5. Run taco pack to create a new .taco file, and then taco run if you wish to test the connector
2. If you don’t want to implement the new capability, and there are no other required code/API changes, you can still update taco-toolkit to the latest and use it to modify and rebuild your connector. However, again, this makes the connector incompatible with versions of Tableau earlier than the minimum version specified by the toolkit.
3. You have the option to not update taco-toolkit and continue maintaining your connector using the version of taco-toolkit that you currently have. However, if breaking changes were introduced in the latest taco-toolkit and Tableau version, your connector might not be compatible with the latest version of Tableau products.

There are some implications that can be taken away from the preceding information:

• Forward compatibility of a connector isn’t guaranteed.
• You could end up with multiple versions of a connector that are compatible with different ranges of Tableau product versions.
• Maintaining only the latest version of a connector, or multiple versions, is up to you. However, maintaining multiple versions of a connector also means you must keep and run multiple versions of taco-toolkit

TACO-Toolkit versioning

The @tableau/taco-toolkit npm package uses the standard npm semantic versioning model. Major and minor toolkit version releases correspond with Tableau major releases. Patch toolkit version releases may or may not correspond with Tableau maintenance releases, depending on if any changes are required in the Tableau product maintenance release.

Corresponding released Tableau product versions will be provided as npm distribution tags (for example, tableau-2022.3, tableau-2022.3.1).

• Major version (x.0.0) increment:
  • Releases on Tableau major release date
  • The package has new features and isn’t backwards compatible with previous Tableau product versions
  • The version is tagged with a Tableau major version (for example, tableau-2022.3)
• Minor version (1.x.0) increment:
  • Releases on Tableau major release date
  • The package has new features and is backwards compatible
  • The version is tagged with a Tableau major version (for example, tableau-2022.3)
• Patch version (1.0.x) increment (minor fixes that require Tableau product maintenance release):
  • Releases on Tableau patch release date
  • The package has minor bug fixes and is backwards compatible
  • The version is tagged with a Tableau patch version (for example, tableau-2022.3.1)
• Patch version (1.0.x) increment (taco-toolkit only minor fixes):
  • Does not correspond with a Tableau release
  • The package has minor bug fixes and is backwards compatible
  • The version is tagged with the latest tag for the same Tableau release

To install a specific version of @tableau/taco-toolkit, you may use

• @tableau/taco-toolkit@ to install with Tableau version
• @tableau/taco-toolkit@ to install with package version

For example, to install TACO CLI for Tableau 2022.3:

• npm install -g @tableau/taco-toolkit@tableau-2022.3