refactor(website): rename docs -> website

website/versioned_docs/version-latest/experiments/any_variables.mdx

@@ -0,0 +1,346 @@
+---
+slug: /experiments/any-variables/
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Any Variables (#1415)
+
+:::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.
+
+:::
+
+Currently, Task only supports string variables. This experiment allows you to
+specify and use the following variable types:
+
+- `string`
+- `bool`
+- `int`
+- `float`
+- `array`
+- `map`
+
+This allows you to have a lot more flexibility in how you use variables in
+Task's templating engine. There are two active proposals for this experiment.
+Click on the tabs below to switch between them.
+
+<Tabs defaultValue="1" queryString="proposal"
+  values={[
+    {label: 'Proposal 1', value: '1'},
+    {label: 'Proposal 2', value: '2'}
+  ]}>
+
+<TabItem value="1">
+
+:::warning
+
+This experiment proposal 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.
+
+:::
+
+## Maps
+
+This proposal removes support for the `sh` keyword in favour of a new syntax for
+dynamically defined variables, This allows you to define a map directly as you
+would for any other type:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      FOO: {a: 1, b: 2, c: 3} # <-- Directly defined map on the `FOO` key
+    cmds:
+      - 'echo {{.FOO.a}}'
+```
+
+## Migration
+
+Taskfiles with dynamically defined variables via the `sh` subkey will no longer
+work with this experiment enabled. In order to keep using dynamically defined
+variables, you will need to migrate your Taskfile to use the new syntax.
+
+Previously, you might have defined a dynamic variable like this:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      CALCULATED_VAR:
+        sh: 'echo hello'
+    cmds:
+      - 'echo {{.CALCULATED_VAR}}'
+```
+
+With this experiment enabled, you will need to remove the `sh` subkey and define
+your command as a string that begins with a `$`. This will instruct Task to
+interpret the string as a command instead of a literal value and the variable
+will be populated with the output of the command. For example:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      CALCULATED_VAR: '$echo hello'
+    cmds:
+      - 'echo {{.CALCULATED_VAR}}'
+```
+
+If your current Taskfile contains a string variable that begins with a `$`, you
+will now need to escape the `$` with a backslash (`\`) to stop Task from
+executing it as a command.
+
+</TabItem>
+
+<TabItem value="2">
+
+:::info
+
+To enable this experiment, set the environment variable:
+`TASK_X_ANY_VARIABLES=2`. Check out [our guide to enabling experiments
+][enabling-experiments] for more information.
+
+:::
+
+## Maps
+
+This proposal maintains backwards-compatibility and the `sh` subkey and adds
+another new `map` subkey for defining map variables:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      FOO:
+        map: {a: 1, b: 2, c: 3} # <-- Defined using the `map' subkey instead of directly on 'FOO'
+      BAR: true # <-- Other types of variables are still defined directly on the key
+      BAZ:
+        sh: 'echo Hello Task' # <-- The `sh` subkey is still supported
+    cmds:
+      - 'echo {{.FOO.a}}'
+```
+
+## Parsing JSON and YAML
+
+In addition to the new `map` keyword, this proposal also adds support for the
+`json` and `yaml` keywords for parsing JSON and YAML strings into real
+objects/arrays. This is similar to the `fromJSON` template function, but means
+that you only have to parse the JSON/YAML once when you declare the variable,
+instead of every time you want to access a value.
+
+Before:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      FOO: '{"a": 1, "b": 2, "c": 3}' # <-- JSON string
+    cmds:
+      - 'echo {{(fromJSON .FOO).a}}' # <-- Parse JSON string every time you want to access a value
+      - 'echo {{(fromJSON .FOO).b}}'
+```
+
+After:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      FOO:
+        json: '{"a": 1, "b": 2, "c": 3}' # <-- JSON string parsed once
+    cmds:
+      - 'echo {{.FOO.a}}' # <-- Access values directly
+      - 'echo {{.FOO.b}}'
+```
+
+## Variables by reference
+
+Lastly, this proposal adds support for defining and passing variables by
+reference. This is really important now that variables can be types other than a
+string. Previously, to send a variable from one task to another, you would have
+to use the templating system to pass it:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      FOO: [A, B, C] # <-- FOO is defined as an array
+    cmds:
+      - task: bar
+        vars:
+          FOO: '{{.FOO}}' # <-- FOO gets converted to a string when passed to bar
+  bar:
+    cmds:
+      - 'echo {{index .FOO 0}}' # <-- FOO is a string so the task outputs '91' which is the ASCII code for '[' instead of the expected 'A'
+```
+
+Unfortunately, this results in the value always being passed as a string as this
+is the output type of the templater and operations on the passed variable may
+not behave as expected. With this proposal, you can now pass variables by
+reference using the `ref` subkey:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      FOO: [A, B, C] # <-- FOO is defined as an array
+    cmds:
+      - task: bar
+        vars:
+          FOO:
+            ref: FOO # <-- FOO gets passed by reference to bar and maintains its type
+  bar:
+    cmds:
+      - 'echo {{index .FOO 0}}' # <-- FOO is still a map so the task outputs 'A' as expected
+```
+
+This means that the type of the variable is maintained when it is passed to
+another Task. This also works the same way when calling `deps` and when defining
+a variable and can be used in any combination:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      FOO: [A, B, C] # <-- FOO is defined as an array
+      BAR:
+        ref: FOO # <-- BAR is defined as a reference to FOO
+    deps:
+      - task: bar
+        vars:
+          BAR:
+            ref: BAR # <-- BAR gets passed by reference to bar and maintains its type
+  bar:
+    cmds:
+      - 'echo {{index .BAR 0}}' # <-- BAR still refers to FOO so the task outputs 'A'
+```
+
+</TabItem></Tabs>
+
+---
+
+## Common to both proposals
+
+Both proposals add support for all other variable types by directly defining
+them in the Taskfile. For example:
+
+### Evaluating booleans
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      BOOL: false
+    cmds:
+      - '{{if .BOOL}}echo foo{{end}}'
+```
+
+### Arithmetic
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      INT: 10
+      FLOAT: 3.14159
+    cmds:
+      - 'echo {{add .INT .FLOAT}}'
+```
+
+### Ranging
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      ARRAY: [1, 2, 3]
+    cmds:
+      - 'echo {{range .ARRAY}}{{.}}{{end}}'
+```
+
+There are many more templating functions which can be used with the new types of
+variables. For a full list, see the [slim-sprig][slim-sprig] documentation.
+
+## Looping over variables
+
+Previously, you would have to use a delimiter separated string to loop over an
+arbitrary list of items in a variable and split them by using the `split` subkey
+to specify the delimiter:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      LIST: 'foo,bar,baz'
+    cmds:
+      - for:
+          var: LIST
+          split: ','
+        cmd: echo {{.ITEM}}
+```
+
+Both of these proposals add support for looping over "collection-type" variables
+using the `for` keyword, so now you are able to loop over a map/array variable
+directly:
+
+```yaml
+version: 3
+
+tasks:
+  foo:
+    vars:
+      LIST: [foo, bar, baz]
+    cmds:
+      - for:
+          var: LIST
+        cmd: echo {{.ITEM}}
+```
+
+When looping over a map we also make an additional `{{.KEY}}` variable availabe
+that holds the string value of the map key. Remember that maps are unordered, so
+the order in which the items are looped over is random.
+
+<!-- prettier-ignore-start -->
+[enabling-experiments]: /experiments/#enabling-experiments
+[slim-sprig]: https://go-task.github.io/slim-sprig/
+<!-- prettier-ignore-end -->

website/versioned_docs/version-latest/experiments/experiments.md

@@ -0,0 +1,131 @@
+---
+slug: /experiments/
+sidebar_position: 6
+---
+
+# Experiments
+
+:::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.
+
+:::
+
+In order to allow Task to evolve quickly, we sometimes roll out breaking changes
+to minor versions behind experimental flags. This allows us to gather feedback
+on breaking changes before committing to a major release. This process can also
+be used to gather feedback on important non-breaking features before their
+design is completed. This document describes the
+[experiment workflow](#workflow) and how you can get involved.
+
+You can view the full list of active experiments in the sidebar submenu to the
+left of the page and click on each one to find out more about it.
+
+## Enabling Experiments
+
+Task uses environment variables to detect whether or not an experiment is
+enabled. All of the experiment variables will begin with the same `TASK_X_`
+prefix followed by the name of the experiment. You can find the exact name for
+each experiment on their respective pages in the sidebar. If the variable is set
+`=1` then it will be enabled. Some experiments may have multiple proposals, in
+which case, you will need to set the variable equal to the number of the
+proposal that you want to enable (`=2`, `=3` etc).
+
+There are three main ways to set the environment variables for an experiment.
+Which method you use depends on how you intend to use the experiment:
+
+1. Prefixing your task commands with the relevant environment variable(s). For
+   example, `TASK_X_{FEATURE}=1 task {my-task}`. This is intended for one-off
+   invocations of Task to test out experimental features.
+1. Adding the relevant environment variable(s) in your "dotfiles" (e.g.
+   `.bashrc`, `.zshrc` etc.). This will permanently enable experimental features
+   for your personal environment.
+
+   ```shell title="~/.bashrc"
+   export TASK_X_FEATURE=1
+   ```
+
+1. Creating a `.env` file in the same directory as your root Taskfile that
+   contains the relevant environment variable(s). This allows you to enable an
+   experimental feature at a project level. If you commit the `.env` file to
+   source control then other users of your project will also have these
+   experiments enabled.
+
+   ```shell title=".env"
+   TASK_X_FEATURE=1
+   ```
+
+## Workflow
+
+Experiments are a way for us to test out new features in Task before committing
+to them in a major release. Because this concept is built around the idea of
+feedback from our community, we have built a workflow for the process of
+introducing these changes. This ensures that experiments are given the attention
+and time that they need and that we are getting the best possible results out of
+them.
+
+The sections below describe the various stages that an experiment must go
+through from its proposal all the way to being released in a major version of
+Task.
+
+### 1. Proposal
+
+All experimental features start with a proposal in the form of a GitHub issue.
+If the maintainers decide that an issue has enough support and is a breaking
+change or is complex/controversial enough to require user feedback, then the
+issue will be marked with the `experiment: proposal` label. At this point, the
+issue becomes a proposal and a period of consultation begins. During this
+period, we request that users provide feedback on the proposal and how it might
+effect their use of Task. It is up to the discretion of the maintainers to
+decide how long this period lasts.
+
+### 2. Draft
+
+Once a proposal's consultation ends, a contributor may pick up the work and
+begin the initial implementation. Once a PR is opened, the maintainers will
+ensure that it meets the requirements for an experimental feature (i.e. flags
+are in the right format etc) and merge the feature. Once this code is released,
+the status will be updated via the `experiment: draft` label. This indicates
+that an implementation is now available for use in a release and the experiment
+is open for feedback.
+
+:::note
+
+During the draft period, major changes to the implementation may be made based
+on the feedback received from users. There are _no stability guarantees_ and
+experimental features may be abandoned _at any time_.
+
+:::
+
+### 3. Candidate
+
+Once an acceptable level of consensus has been reached by the community and
+feedback/changes are less frequent/significant, the status may be updated via
+the `experiment: candidate` label. This indicates that a proposal is _likely_ to
+accepted and will enter a period for final comments and minor changes.
+
+### 4. Stable
+
+Once a suitable amount of time has passed with no changes or feedback, an
+experiment will be given the `experiment: stable` label. At this point, the
+functionality will be treated like any other feature in Task and any changes
+_must_ be backward compatible. This allows users to migrate to the new
+functionality without having to worry about anything breaking in future
+releases. This provides the best experience for users migrating to a new major
+version.
+
+### 5. Released
+
+When making a new major release of Task, all experiments marked as
+`experiment: stable` will move to `experiment: released` and their behaviors
+will become the new default in Task. Experiments in an earlier stage (i.e. not
+stable) cannot be released and so will continue to be experiments in the new
+version.
+
+### Abandoned / Superseded
+
+If an experiment is unsuccessful at any point then it will be given the
+`experiment: abandoned` or `experiment: superseded` labels depending on which is
+more suitable. These experiments will be removed from Task.

website/versioned_docs/version-latest/experiments/gentle_force.md

@@ -0,0 +1,49 @@
+---
+slug: /experiments/gentle-force/
+---
+
+# Gentle Force (#1200)
+
+:::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
+expect the direct task they are calling to be forced and _not_ all of its
+dependant tasks.
+
+This experiment changes the `--force` flag to only force the directly called
+task. All dependant tasks will have their statuses checked as normal and will
+only run if Task considers them to be out of date. A new `--force-all` flag will
+also be added to maintain the current behavior for users that need this
+functionality.
+
+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!
+
+<!-- prettier-ignore-start -->
+[enabling-experiments]: /experiments/#enabling-experiments
+<!-- prettier-ignore-end -->

website/versioned_docs/version-latest/experiments/remote_taskfiles.md

@@ -0,0 +1,105 @@
+---
+slug: /experiments/remote-taskfiles/
+---
+
+# Remote Taskfiles (#1317)
+
+:::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:
+
+```yaml
+version: '3'
+
+includes:
+  my-remote-namespace: https://raw.githubusercontent.com/my-org/my-repo/main/Taskfile.yml
+```
+
+This works exactly the same way that including a local file does. Any tasks in
+the remote Taskfile will be available to run from your main Taskfile via the
+namespace `my-remote-namespace`. For example, if the remote file contains the
+following:
+
+```yaml
+version: '3'
+
+tasks:
+  hello:
+    silent: true
+    cmds:
+      - echo "Hello from the remote Taskfile!"
+```
+
+and you run `task my-remote-namespace:hello`, it will print the text: "Hello
+from the remote Taskfile!" to your console.
+
+## Security
+
+Running commands from sources that you do not control is always a potential
+security risk. For this reason, we have added some checks when using remote
+Taskfiles:
+
+1. When running a task from a remote Taskfile for the first time, Task will
+   print a warning to the console asking you to check that you are sure that you
+   trust the source of the Taskfile. If you do not accept the prompt, then Task
+   will exit with code `104` (not trusted) and nothing will run. If you accept
+   the prompt, the remote Taskfile will run and further calls to the remote
+   Taskfile will not prompt you again.
+2. Whenever you run a remote Taskfile, Task will create and store a checksum of
+   the file that you are running. If the checksum changes, then Task will print
+   another warning to the console to inform you that the contents of the remote
+   file has changed. If you do not accept the prompt, then Task will exit with
+   code `104` (not trusted) and nothing will run. If you accept the prompt, the
+   checksum will be updated and the remote Taskfile will run.
+
+Sometimes you need to run Task in an environment that does not have an
+interactive terminal, so you are not able to accept a prompt. In these cases you
+are able to tell task to accept these prompts automatically by using the `--yes`
+flag. Before enabling this flag, you should:
+
+1. Be sure that you trust the source and contents of the remote Taskfile.
+2. Consider using a pinned version of the remote Taskfile (e.g. A link
+   containing a commit hash) to prevent Task from automatically accepting a
+   prompt that says a remote Taskfile has changed.
+
+Task currently supports both `http` and `https` URLs. However, the `http`
+requests will not execute by default unless you run the task with the
+`--insecure` flag. This is to protect you from accidentally running a remote
+Taskfile that is hosted on and unencrypted connection. Sources that are not
+protected by TLS are vulnerable to [man-in-the-middle
+attacks][man-in-the-middle-attacks] and should be avoided unless you know what
+you are doing.
+
+## Caching & Running Offline
+
+Whenever you run a remote Taskfile, the latest copy will be downloaded from the
+internet and cached locally. If for whatever reason, you lose access to the
+internet, you will still be able to run your tasks by specifying the `--offline`
+flag. This will tell Task to use the latest cached version of the file instead
+of trying to download it. You are able to use the `--download` flag to update
+the cached version of the remote files without running any tasks.
+
+By default, Task will timeout requests to download remote files after 10 seconds
+and look for a cached copy instead. This timeout can be configured by setting
+the `--timeout` flag and specifying a duration. For example, `--timeout 5s` will
+set the timeout to 5 seconds.
+
+<!-- prettier-ignore-start -->
+[enabling-experiments]: /experiments/#enabling-experiments
+[man-in-the-middle-attacks]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
+<!-- prettier-ignore-end -->

website/versioned_docs/version-latest/experiments/template.md

@@ -0,0 +1,42 @@
+---
+# This is a template for an experiments documentation
+# Copy this page and fill in the details as necessary
+title: '--- Template ---'
+sidebar_position: -1 # Always push to the top
+draft: true # Hide in production
+---
+
+# \{Name of Experiment\} (#\{Issue\})
+
+:::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\}
+
+<!-- prettier-ignore-start -->
+[enabling-experiments]: /experiments/#enabling-experiments
+<!-- prettier-ignore-end -->