go/task
go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2024-12-14 10:52:43 +02:00
Code Issues Releases Activity

docs: taskfile versions (#1666)

Browse Source
This commit is contained in:
Pete Davison 2024-06-14 00:49:21 +01:00 committed by GitHub
parent ea85909e8b
commit 53dd0b138a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 44 additions and 235 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

279
website/docs/taskfile_versions.mdx
View File

@ -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/