What is 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 until v1
is reached which is the most minimal version and must be available for any existing command.
Latest version (default)
If no version is specified, by default the latest available version is used, which is the highest available version of each command:
pipeline: - log: message: "Hello World!"
Is the same as:
pipeline: - log:latest: message: "Hello World!"
Is the same as:
headers: version: latest pipeline: - log:: message: "Hello World!"
Add Comment