From 53dd0b138ae8405ce9d40020f290e89b167ffd34 Mon Sep 17 00:00:00 2001 From: Pete Davison Date: Fri, 14 Jun 2024 00:49:21 +0100 Subject: [PATCH] docs: taskfile versions (#1666) --- website/docs/taskfile_versions.mdx | 279 +++++------------------------ 1 file changed, 44 insertions(+), 235 deletions(-) diff --git a/website/docs/taskfile_versions.mdx b/website/docs/taskfile_versions.mdx index b85a6f7a..507715e8 100644 --- a/website/docs/taskfile_versions.mdx +++ b/website/docs/taskfile_versions.mdx @@ -5,259 +5,68 @@ sidebar_position: 5 # Taskfile Versions -The Taskfile syntax and features changed with time. This document explains what -changed on each version and how to upgrade your Taskfile. +The Taskfile schema slowly changes as new features are added and old ones are +removed. This document explains how to use a Taskfile's schema version to ensure +that the users of your Taskfile are using the correct versions of Task. -## What the Taskfile version mean +## What the Taskfile version means -The Taskfile version follows the Task version. E.g. the change to Taskfile -version `2` means that Task `v2.0.0` should be release to support it. - -The `version:` key on Taskfile accepts a semver string, so either `2`, `2.0` or -`2.0.0` is accepted. If you choose to use `2.0` Task will not enable future -`2.1` features, but if you choose to use `2`, then any `2.x.x` features will be -available, but not `3.0.0+`. - -## Version 3 ![latest](https://img.shields.io/badge/latest-brightgreen) - -These are some major changes done on `v3`: - -- Task's output will now be colored -- Added support for `.env` like files -- Added `label:` setting to task so one can override how the task name appear in - the logs -- A global `method:` was added to allow setting the default method, and Task's - default changed to `checksum` -- Two magic variables were added when using `status:`: `CHECKSUM` and - `TIMESTAMP` which contains, respectively, the XXH3 checksum and greatest - modification timestamp of the files listed on `sources:` -- Also, the `TASK` variable is always available with the current task name -- CLI variables are always treated as global variables -- Added `dir:` option to `includes` to allow choosing on which directory an - included Taskfile will run: +The schema version at the top of every Taskfile corresponds to a version of the +Task CLI, and by extension, the features that are provided by that version. When +creating a Taskfile, you should specify the _minimum_ version of Task that +supports the features you require. If you try to run a Taskfile with a version +of Task that does not meet this minimum required version, it will exit with an +error. For example, given a Taskfile that starts with: ```yaml -includes: - docs: - taskfile: ./docs - dir: ./docs +version: '3.2.1' ``` -- Implemented short task syntax. All below syntaxes are equivalent: +When executed with Task `v3.2.0`, it will exit with an error. Running with +version `v3.2.1` or higher will work as expected. + +Task accepts any [SemVer][semver] compatible string including versions which +omit the minor or patch numbers. For example, `3`, `3.0`, and `3.0.0` all mean +the same thing and are all valid. Most Taskfiles only specify the major version +number. However it can be useful to be more specific when you intend to share a +Taskfile with others. + +For example, the Taskfile below makes use of aliases: ```yaml version: '3' tasks: - print: + hello: + aliases: + - hi + - hey cmds: - - echo "Hello, World!" + - echo "Hello, world!" ``` +Aliases were introduced in Task `v3.17.0`, but the Taskfile only specifies `3` +as the version. This means that a user who has `v3.16.0` or lower installed will +get a potentially confusing error message when trying to run the Task as the +Taskfile specifies that any version greater or equal to `v3.0.0` is fine. + +Instead, we should start the file like this: + ```yaml -version: '3' - -tasks: - print: - - echo "Hello, World!" +version: '3.17' ``` -```yaml -version: '3' +Now when someone tries to run the Taskfile with an older version of Task, they +will receive an error prompting them to upgrade their version of Task to +`v3.17.0` or greater. -tasks: - print: echo "Hello, World!" -``` +## Versions 1 & 2 -- There was a major refactor on how variables are handled. They're now easier to - understand. The `expansions:` setting was removed as it became unnecessary. - This is the order in which Task will process variables, each level can see the - variables set by the previous one and override those. - - Environment variables - - Global + CLI variables - - Call variables - - Task variables +Version 1 and 2 of Task are no longer officially supported and anyone still +using them is strongly encouraged to upgrade to the latest version of Task. -## Version 2.6 +While `version: 2` of Task did support schema versions, the behavior did not +work in quite the same way and cannot be relied upon for the purposes discussed +above. -:::caution - -v2 schemas are [no longer supported by the latest version of -Task][deprecate-version-2-schema]. - -::: - -Version 2.6 comes with `preconditions` stanza in tasks. - -```yaml -version: '2' - -tasks: - upload_environment: - preconditions: - - test -f .env - cmds: - - aws s3 cp .env s3://myenvironment -``` - -Please check the [documentation][includes] - -## Version 2.2 - -:::caution - -v2 schemas are [no longer supported by the latest version of -Task][deprecate-version-2-schema]. - -::: - -Version 2.2 comes with a global `includes` options to include other Taskfiles: - -```yaml -version: '2' - -includes: - docs: ./documentation # will look for ./documentation/Taskfile.yml - docker: ./DockerTasks.yml -``` - -## Version 2.1 - -:::caution - -v2 schemas are [no longer supported by the latest version of -Task][deprecate-version-2-schema]. - -::: - -Version 2.1 includes a global `output` option, to allow having more control over -how commands output are printed to the console (see [documentation][output] for -more info): - -```yaml -version: '2' - -output: prefixed - -tasks: - server: - cmds: - - go run main.go - prefix: server -``` - -From this version it's also possible to ignore errors of a command or task -(check documentation [here][ignore_errors]): - -```yaml -version: '2' - -tasks: - example-1: - cmds: - - cmd: exit 1 - ignore_error: true - - echo "This will be print" - - example-2: - cmds: - - exit 1 - - echo "This will be print" - ignore_error: true -``` - -## Version 2.0 - -:::caution - -v2 schemas are [no longer supported by the latest version of -Task][deprecate-version-2-schema]. - -::: - -At version 2, we introduced the `version:` key, to allow us to evolve Task with -new features without breaking existing Taskfiles. The new syntax is as follows: - -```yaml -version: '2' - -tasks: - echo: - cmds: - - echo "Hello, World!" -``` - -Version 2 allows you to write global variables directly in the Taskfile, if you -don't want to create a `Taskvars.yml`: - -```yaml -version: '2' - -vars: - GREETING: Hello, World! - -tasks: - greet: - cmds: - - echo "{{.GREETING}}" -``` - -The variable priority order changed to the following: - -1. Task variables -2. Call variables -3. Taskfile variables -4. Taskvars file variables -5. Environment variables - -A new global option was added to configure the number of variables expansions -(which default to 2): - -```yaml -version: '2' - -expansions: 3 - -vars: - FOO: foo - BAR: bar - BAZ: baz - FOOBAR: '{{.FOO}}{{.BAR}}' - FOOBARBAZ: '{{.FOOBAR}}{{.BAZ}}' - -tasks: - default: - cmds: - - echo "{{.FOOBARBAZ}}" -``` - -## Version 1 - -:::caution - -v1 schema support was removed in Task >= v3.0.0. - -::: - -In the first version of the `Taskfile`, the `version:` key was not available, -because the tasks was in the root of the YAML document. Like this: - -```yaml -echo: - cmds: - - echo "Hello, World!" -``` - -The variable priority order was also different: - -1. Call variables -2. Environment -3. Task variables -4. `Taskvars.yml` variables - -{/* prettier-ignore-start */} -[deprecate-version-2-schema]: ./deprecations/version_2_schema.mdx -[output]: ./usage.mdx#output-syntax -[ignore_errors]: ./usage.mdx#ignore-errors -[includes]: ./usage.mdx#including-other-taskfiles -{/* prettier-ignore-end */} +[semver]: https://semver.org/