What is a Command Versioning?

Each command can be available in different versions like v1, v2, v3 and so on. This is to support downwards compatibility in pipeline scripts. This way a newer version of a command will not break old pipeline code since it can be specified in a pipeline which exact command version to be used.

Which commands are available in which versions can be found in the commands reference docs.

Specify the version per command (locally)​

In order to use a specific version of a single command, you need to add it as suffix :<version> to the command name, whereas <version> needs to be replaced by the version to be used. For example :v1, :v2, :v3, and so on.

Here is an example to use the log command with exact version v3 in a pipeline:

pipeline:
  - log:v3:
      message: "Hello World!"   

Here, we use version v4 of command log:

pipeline:
  - log:v4:
      message: "Hello World!"    

Specify the version per pipeline (globally)​

Instead of defining the version for each command, you can also set it globally for all commands of a pipeline using the header version. Example:

headers:
  version: v4
pipeline:
  - log:
      message: "Hello World!"

In this case all commands defined in the pipeline will use version v4 without the need of local definition per command.

In case you combine the header version with local version on a command, the local one wins:

headers:
  version: v4
pipeline:
  - log:v5:
      message: "Hello World!"

In this example, the log command is used with version v5.

Version fallback (backwards compatibility)​

Defining a version means you specify the highest version number to be used. If this version is not available, the next lower available version is loaded instead.

In case you specify a version like v5 for example, it will be tried to load the command with this exact version. In case no such command with this version exists, the next lower version will be looked up, like v4 for example. If no command with this version exists, the next lower version v3 is tried, and so on.

Default version (latest)

If no version is specified, by default the latest available version is used:

pipeline:
  - log:
      message: "Hello World!"   

Is the same as:

pipeline:
  - log:latest:
      message: "Hello World!"  

Is the same as:

headers:
  version: latest
pipeline:
  - log:latest:
      message: "Hello World!"