docs: taskfile versions (#1666)

Author: pd93

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:
-
-```yaml
-version: '3'
-
-tasks:
-  print:
-    cmds:
-      - echo "Hello, World!"
-```
+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.
 
-```yaml
-version: '3'
+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.
 
-tasks:
-  print:
-    - echo "Hello, World!"
-```
+For example, the Taskfile below makes use of aliases:
 
 ```yaml
 version: '3'
 
 tasks:
-  print: echo "Hello, World!"
-```
-
-- 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 2.6
-
-:::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:
+  hello:
+    aliases:
+      - hi
+      - hey
     cmds:
-      - echo "Hello, World!"
+      - 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
+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.
 
-A new global option was added to configure the number of variables expansions
-(which default to 2):
+Instead, we should start the file like this:
 
 ```yaml
-version: '2'
-
-expansions: 3
-
-vars:
-  FOO: foo
-  BAR: bar
-  BAZ: baz
-  FOOBAR: '{{.FOO}}{{.BAR}}'
-  FOOBARBAZ: '{{.FOOBAR}}{{.BAZ}}'
-
-tasks:
-  default:
-    cmds:
-      - echo "{{.FOOBARBAZ}}"
+version: '3.17'
 ```
 
-## Version 1
-
-:::caution
+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.
 
-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!"
-```
+## Versions 1 & 2
 
-The variable priority order was also different:
+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.
 
-1. Call variables
-2. Environment
-3. Task variables
-4. `Taskvars.yml` variables
+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.
 
-{/* 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/