chore: update and re-order taskfile versions doc

go-task · May 31, 2023 · 85a190b · 85a190b
1 parent 803e94a
commit 85a190b
Showing 1 changed file with 143 additions and 107 deletions.
diff --git a/docs/docs/taskfile_versions.md b/docs/docs/taskfile_versions.md
@@ -18,86 +18,122 @@ The `version:` key on Taskfile accepts a semver string, so either `2`, `2.0` or
 `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 1
+## Version 3 ![latest](https://img.shields.io/badge/latest-brightgreen)
 
-> NOTE: Taskfiles in version 1 are not supported on Task >= v3.0.0 anymore.
+These are some major changes done on `v3`:
 
-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:
+- 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 md5 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:
 
 ```yaml
-echo:
-  cmds:
-    - echo "Hello, World!"
+includes:
+  docs:
+    taskfile: ./docs
+    dir: ./docs
 ```
 
-The variable priority order was also different:
+- Implemented short task syntax. All below syntaxes are equivalent:
 
-1. Call variables
-2. Environment
-3. Task variables
-4. `Taskvars.yml` variables
+```yaml
+version: '3'
 
-## Version 2.0
+tasks:
+  print:
+    cmds:
+      - echo "Hello, World!"
+```
 
-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: '3'
+
+tasks:
+  print:
+    - echo "Hello, World!"
+```
 
 ```yaml
-version: '2'
+version: '3'
 
 tasks:
-  echo:
-    cmds:
-      - echo "Hello, World!"
+  print: 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`:
+- 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 schema support is [deprecated][deprecate-version-2-schema] and will be
+removed in a future release.
+
+:::
+
+Version 2.6 comes with `preconditions` stanza in tasks.
 
 ```yaml
 version: '2'
 
-vars:
-  GREETING: Hello, World!
-
 tasks:
-  greet:
+  upload_environment:
+    preconditions:
+      - test -f .env
     cmds:
-      - echo "{{.GREETING}}"
+      - aws s3 cp .env s3://myenvironment
 ```
 
-The variable priority order changed to the following:
+Please check the [documentation][includes]
 
-1. Task variables
-2. Call variables
-3. Taskfile variables
-4. Taskvars file variables
-5. Environment variables
+[output]: usage.md#output-syntax
+[ignore_errors]: usage.md#ignore-errors
+[includes]: usage.md#including-other-taskfiles
 
-A new global option was added to configure the number of variables expansions
-(which default to 2):
+## Version 2.2
 
-```yaml
-version: '2'
+:::caution
 
-expansions: 3
+v2 schema support is [deprecated][deprecate-version-2-schema] and will be
+removed in a future release.
 
-vars:
-  FOO: foo
-  BAR: bar
-  BAZ: baz
-  FOOBAR: '{{.FOO}}{{.BAR}}'
-  FOOBARBAZ: '{{.FOOBAR}}{{.BAZ}}'
+:::
 
-tasks:
-  default:
-    cmds:
-      - echo "{{.FOOBARBAZ}}"
+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 schema support is [deprecated][deprecate-version-2-schema] and will be
+removed in a future release.
+
+:::
+
 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):
@@ -134,95 +170,95 @@ tasks:
     ignore_error: true
 ```
 
-## Version 2.2
+## Version 2.0
 
-Version 2.2 comes with a global `includes` options to include other Taskfiles:
+:::caution
+
+v2 schema support is [deprecated][deprecate-version-2-schema] and will be
+removed in a future release.
+
+:::
+
+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'
 
-includes:
-  docs: ./documentation # will look for ./documentation/Taskfile.yml
-  docker: ./DockerTasks.yml
+tasks:
+  echo:
+    cmds:
+      - echo "Hello, World!"
 ```
 
-## Version 2.6
-
-Version 2.6 comes with `preconditions` stanza in tasks.
+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:
-  upload_environment:
-    preconditions:
-      - test -f .env
+  greet:
     cmds:
-      - aws s3 cp .env s3://myenvironment
+      - echo "{{.GREETING}}"
 ```
 
-Please check the [documentation][includes]
-
-[output]: usage.md#output-syntax
-[ignore_errors]: usage.md#ignore-errors
-[includes]: usage.md#including-other-taskfiles
-
-## Version 3
+The variable priority order changed to the following:
 
-These are some major changes done on `v3`:
+1. Task variables
+2. Call variables
+3. Taskfile variables
+4. Taskvars file variables
+5. Environment variables
 
-- 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 md5 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:
+A new global option was added to configure the number of variables expansions
+(which default to 2):
 
 ```yaml
-includes:
-  docs:
-    taskfile: ./docs
-    dir: ./docs
-```
+version: '2'
 
-- Implemented short task syntax. All below syntaxes are equivalent:
+expansions: 3
 
-```yaml
-version: '3'
+vars:
+  FOO: foo
+  BAR: bar
+  BAZ: baz
+  FOOBAR: '{{.FOO}}{{.BAR}}'
+  FOOBARBAZ: '{{.FOOBAR}}{{.BAZ}}'
 
 tasks:
-  print:
+  default:
     cmds:
-      - echo "Hello, World!"
+      - echo "{{.FOOBARBAZ}}"
 ```
 
-```yaml
-version: '3'
+## Version 1
 
-tasks:
-  print:
+:::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!"
 ```
 
-```yaml
-version: '3'
+The variable priority order was also different:
 
-tasks:
-  print: echo "Hello, World!"
-```
+1. Call variables
+2. Environment
+3. Task variables
+4. `Taskvars.yml` variables
 
-- 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
+<!-- prettier-ignore-start -->
+[deprecate-version-2-schema]: https://github.com/go-task/task/issues/1197
+<!-- prettier-ignore-end -->