From 212ff4230472130054ce0e2aa163937a2be3bff5 Mon Sep 17 00:00:00 2001 From: Pete Davison Date: Fri, 29 Dec 2023 20:24:23 +0000 Subject: [PATCH] docs: improved experimental docs formatting (#1445) * docs: remove section from styleguide * docs: update format of experiments/deprecations docs --- docs/docs/deprecations/template.md | 13 +++++--- docs/docs/deprecations/version_2_schema.md | 14 ++++++--- docs/docs/experiments/any_variables.md | 30 +++++++++++++++--- docs/docs/experiments/experiments.md | 10 +++--- docs/docs/experiments/gentle_force.md | 33 +++++++++++++++++--- docs/docs/experiments/remote_taskfiles.md | 20 ++++++++++-- docs/docs/experiments/template.md | 36 +++++++++++++++++----- docs/docs/styleguide.md | 15 --------- 8 files changed, 123 insertions(+), 48 deletions(-) diff --git a/docs/docs/deprecations/template.md b/docs/docs/deprecations/template.md index 50d7cce2..dee9802a 100644 --- a/docs/docs/deprecations/template.md +++ b/docs/docs/deprecations/template.md @@ -6,11 +6,16 @@ sidebar_position: -1 # Always push to the top draft: true # Hide in production --- -# \{Name of Deprecated Feature\} +# \{Name of Deprecated Feature\} (#\{Issue\}) -- Issue: #\{issue\} -- Breaks: - - \{list any existing functionality that will be broken by this experiment\} +:::warning + +This deprecation breaks the following functionality: + +- \{list any existing functionality that will be broken by this deprecation\} +- \{if there are no breaking changes, remove this admonition\} + +::: \{Short description of the feature/behavior and why it is being deprecated\} diff --git a/docs/docs/deprecations/version_2_schema.md b/docs/docs/deprecations/version_2_schema.md index 7de6d8e2..c6f5471a 100644 --- a/docs/docs/deprecations/version_2_schema.md +++ b/docs/docs/deprecations/version_2_schema.md @@ -2,12 +2,16 @@ slug: /deprecations/version-2-schema/ --- -# Version 2 Schema +# Version 2 Schema (#1197) -- Issue: #1197 -- Breaks: - - Any Taskfiles that use the version 2 schema - - `Taskvar.yml` files +:::warning + +This deprecation breaks the following functionality: + +- Any Taskfiles that use the version 2 schema +- `Taskvar.yml` files + +::: The Taskfile v2 schema was introduced in March 2018 and replaced by version 3 in August the following year. Users have had a long time to update and so we feel diff --git a/docs/docs/experiments/any_variables.md b/docs/docs/experiments/any_variables.md index eb9c1819..8f54089b 100644 --- a/docs/docs/experiments/any_variables.md +++ b/docs/docs/experiments/any_variables.md @@ -2,12 +2,31 @@ slug: /experiments/any-variables/ --- -# Any Variables +# Any Variables (#1415) -- Issue: #1415 -- Environment variable: `TASK_X_ANY_VARIABLES=1` -- Breaks: - - Dynamically defined variables (using the `sh` keyword) +:::caution + +All experimental features are subject to breaking changes and/or removal _at any +time_. We strongly recommend that you do not use these features in a production +environment. They are intended for testing and feedback only. + +::: + +:::warning + +This experiment breaks the following functionality: + +- Dynamically defined variables (using the `sh` keyword) + +::: + +:::info + +To enable this experiment, set the environment variable: +`TASK_X_ANY_VARIABLES=1`. Check out [our guide to enabling experiments +][enabling-experiments] for more information. + +::: Currently, Task only supports string variables. This experiment allows you to specify and use the following variable types: @@ -179,5 +198,6 @@ will now need to escape the `$` with a backslash (`\`) to stop Task from executing it as a command. +[enabling-experiments]: /experiments/#enabling-experiments [slim-sprig]: https://go-task.github.io/slim-sprig/ diff --git a/docs/docs/experiments/experiments.md b/docs/docs/experiments/experiments.md index e26a6e31..15f7bf58 100644 --- a/docs/docs/experiments/experiments.md +++ b/docs/docs/experiments/experiments.md @@ -22,7 +22,9 @@ the current set of experimental features and their status in the You can view a full list of active experiments in the "Experiments" section of the sidebar. -You can enable an experimental feature by: +## Enabling Experiments + +You can enable an experimental feature by doing one of the following: 1. Using the relevant environment variable in front of a task command. For example, `TASK_X_{FEATURE}=1 task {my-task}`. This is intended for one-off @@ -31,10 +33,10 @@ You can enable an experimental feature by: `.zshrc` etc.). This is intended for permanently enabling experimental features in your environment. 1. Creating a `.env` file in the same directory as your root Taskfile that - contains the relevant environment variables. e.g. + contains the relevant environment variables. This allows you to enable an + experimental feature at a project level. For example: -```shell -# .env +```shell title=".env" TASK_X_FEATURE=1 ``` diff --git a/docs/docs/experiments/gentle_force.md b/docs/docs/experiments/gentle_force.md index 5118ac5a..d468770c 100644 --- a/docs/docs/experiments/gentle_force.md +++ b/docs/docs/experiments/gentle_force.md @@ -2,12 +2,31 @@ slug: /experiments/gentle-force/ --- -# Gentle Force +# Gentle Force (#1200) -- Issue: #1200 -- Environment variable: `TASK_X_FORCE=1` -- Breaks: - - `--force` flag +:::caution + +All experimental features are subject to breaking changes and/or removal _at any +time_. We strongly recommend that you do not use these features in a production +environment. They are intended for testing and feedback only. + +::: + +:::warning + +This experiment breaks the following functionality: + +- The `--force` flag + +::: + +:::info + +To enable this experiment, set the environment variable: `TASK_X_FORCE=1`. Check +out [our guide to enabling experiments ][enabling-experiments] for more +information. + +::: The `--force` flag currently forces _all_ tasks to run regardless of the status checks. This can be useful, but we have found that most of the time users only @@ -24,3 +43,7 @@ If you want to migrate, but continue to force all dependant tasks to run, you should replace all uses of the `--force` flag with `--force-all`. Alternatively, if you want to adopt the new behavior, you can continue to use the `--force` flag as you do now! + + +[enabling-experiments]: /experiments/#enabling-experiments + diff --git a/docs/docs/experiments/remote_taskfiles.md b/docs/docs/experiments/remote_taskfiles.md index e2fab674..40236509 100644 --- a/docs/docs/experiments/remote_taskfiles.md +++ b/docs/docs/experiments/remote_taskfiles.md @@ -2,10 +2,23 @@ slug: /experiments/remote-taskfiles/ --- -# Remote Taskfiles +# Remote Taskfiles (#1317) -- Issue: #1317 -- Environment variable: `TASK_X_REMOTE_TASKFILES=1` +:::caution + +All experimental features are subject to breaking changes and/or removal _at any +time_. We strongly recommend that you do not use these features in a production +environment. They are intended for testing and feedback only. + +::: + +:::info + +To enable this experiment, set the environment variable: +`TASK_X_REMOTE_TASKFILES=1`. Check out [our guide to enabling experiments +][enabling-experiments] for more information. + +::: This experiment allows you to specify a remote Taskfile URL when including a Taskfile. For example: @@ -87,5 +100,6 @@ the `--timeout` flag and specifying a duration. For example, `--timeout 5s` will set the timeout to 5 seconds. +[enabling-experiments]: /experiments/#enabling-experiments [man-in-the-middle-attacks]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack diff --git a/docs/docs/experiments/template.md b/docs/docs/experiments/template.md index 1d13ed82..37ac9987 100644 --- a/docs/docs/experiments/template.md +++ b/docs/docs/experiments/template.md @@ -6,15 +6,37 @@ sidebar_position: -1 # Always push to the top draft: true # Hide in production --- -# \{Name of Experiment\} +# \{Name of Experiment\} (#\{Issue\}) -- Issue: #\{issue\} -- Environment variable: `TASK_X_{feature}` -- Breaks: - - \{list any existing functionality that will be broken by this experiment\} -- Deprecations: - - \{link to any deprecation pages related to this experiment\} +:::caution + +All experimental features are subject to breaking changes and/or removal _at any +time_. We strongly recommend that you do not use these features in a production +environment. They are intended for testing and feedback only. + +::: + +:::warning + +This experiment breaks the following functionality: + +- \{list any existing functionality that will be broken by this experiment\} +- \{if there are no breaking changes, remove this admonition\} + +::: + +:::info + +To enable this experiment, set the environment variable: `TASK_X_{feature}=1`. +Check out [our guide to enabling experiments ][enabling-experiments] for more +information. + +::: \{Short description of the feature\} \{Short explanation of how users should migrate to the new behavior\} + + +[enabling-experiments]: /experiments/#enabling-experiments + diff --git a/docs/docs/styleguide.md b/docs/docs/styleguide.md index 9017af1c..00a62e67 100644 --- a/docs/docs/styleguide.md +++ b/docs/docs/styleguide.md @@ -14,21 +14,6 @@ followed. Feel free to disagree and proceed differently at some point if you need or want to. Also, feel free to open issues or pull requests with improvements to this guide. -## Use `Taskfile.yml` and not `taskfile.yml` - -```yaml -# bad -taskfile.yml - - -# good -Taskfile.yml -``` - -This is important especially for Linux users. Windows and macOS have case -insensitive filesystems, so `taskfile.yml` will end up working, even that not -officially supported. On Linux, only `Taskfile.yml` will work, though. - ## Use the correct order of keywords - `version:`