go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2025-08-10 22:42:19 +02:00
Code Issues Releases Activity

docs: improvements/corrections to experiments doc

Browse Source
This commit is contained in:
Pete Davison
2024-01-17 10:53:51 +00:00
parent dc3cf1cb16
commit f1e2fee088
1 changed files with 57 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
docs/docs/experiments/experiments.md
View File

@@ -13,39 +13,49 @@ environment. They are intended for testing and feedback only.
::: :::
In order to allow Task to evolve quickly, we roll out breaking changes to minor In order to allow Task to evolve quickly, we sometimes roll out breaking changes
versions behind experimental flags. This allows us to gather feedback on to minor versions behind experimental flags. This allows us to gather feedback
breaking changes before committing to a major release. This document describes on breaking changes before committing to a major release. This process can also
the current set of experimental features and their status in the be used to gather feedback on important non-breaking features before their
[workflow](#workflow). design is completed. This document describes the
[experiment workflow](#workflow) and how you can get involved.
You can view a full list of active experiments in the "Experiments" section of You can view the full list of active experiments in the sidebar submenu to the
the sidebar. left of the page and click on each one to find out more about it.
## Enabling Experiments ## Enabling Experiments
You can enable an experimental feature by doing one of the following: 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).
1. Using the relevant environment variable in front of a task command. For 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 example, `TASK_X_{FEATURE}=1 task {my-task}`. This is intended for one-off
invocations of Task to test out experimental features. invocations of Task to test out experimental features.
1. Using the relevant environment variable in your "dotfiles" (e.g. `.bashrc`, 1. Adding the relevant environment variable(s) in your "dotfiles" (e.g.
`.zshrc` etc.). This is intended for permanently enabling experimental `.bashrc`, `.zshrc` etc.). This will permanently enable experimental features
features in your environment. 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 1. Creating a `.env` file in the same directory as your root Taskfile that
contains the relevant environment variables. This allows you to enable an contains the relevant environment variable(s). This allows you to enable an
experimental feature at a project level. For example: 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" ```shell title=".env"
TASK_X_FEATURE=1 TASK_X_FEATURE=1
``` ```
## Current Experimental Features and Deprecations
Each section below details an experiment or deprecation and explains what the
flags/environment variables to enable the experiment are and how the feature's
behavior will change. It will also explain what you need to do to migrate any
existing Taskfiles to the new behavior.
## Workflow ## Workflow
@@ -65,11 +75,11 @@ Task.
All experimental features start with a proposal in the form of a GitHub issue. 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 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 change or is complex/controversial enough to require user feedback, then the
issue will be marked with the ![proposal] label. At this point, the issue issue will be marked with the `experiment: proposal` label. At this point, the
becomes a proposal and a period of consultation begins. During this period, we issue becomes a proposal and a period of consultation begins. During this
request that users provide feedback on the proposal and how it might effect period, we request that users provide feedback on the proposal and how it might
their use of Task. It is up to the discretion of the maintainers to decide how effect their use of Task. It is up to the discretion of the maintainers to
long this period lasts. decide how long this period lasts.
### 2. Draft ### 2. Draft
@@ -77,9 +87,9 @@ 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 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 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, are in the right format etc) and merge the feature. Once this code is released,
the status will be updated via the ![draft] label. This indicates that an the status will be updated via the `experiment: draft` label. This indicates
implementation is now available for use in a release and the experiment is open that an implementation is now available for use in a release and the experiment
for feedback. is open for feedback.
:::note :::note
@@ -93,37 +103,29 @@ experimental features may be abandoned _at any time_.
Once an acceptable level of consensus has been reached by the community and 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 feedback/changes are less frequent/significant, the status may be updated via
the ![candidate] label. This indicates that a proposal is _likely_ to accepted the `experiment: candidate` label. This indicates that a proposal is _likely_ to
and will enter a period for final comments and minor changes. accepted and will enter a period for final comments and minor changes.
### 4. Stable ### 4. Stable
Once a suitable amount of time has passed with no changes or feedback, an Once a suitable amount of time has passed with no changes or feedback, an
experiment will be given the ![stable] label. At this point, the functionality experiment will be given the `experiment: stable` label. At this point, the
will be treated like any other feature in Task and any changes _must_ be functionality will be treated like any other feature in Task and any changes
backward compatible. This allows users to migrate to the new functionality _must_ be backward compatible. This allows users to migrate to the new
without having to worry about anything breaking in future releases. This functionality without having to worry about anything breaking in future
provides the best experience for users migrating to a new major version. releases. This provides the best experience for users migrating to a new major
version.
### 5. Released ### 5. Released
When making a new major release of Task, all experiments marked as ![stable] When making a new major release of Task, all experiments marked as
will move to ![released] and their behaviors will become the new default in `experiment: stable` will move to `experiment: released` and their behaviors
Task. Experiments in an earlier stage (i.e. not stable) cannot be released and will become the new default in Task. Experiments in an earlier stage (i.e. not
so will continue to be experiments in the new version. stable) cannot be released and so will continue to be experiments in the new
version.
### Abandoned / Superseded ### Abandoned / Superseded
If an experiment is unsuccessful at any point then it will be given the If an experiment is unsuccessful at any point then it will be given the
![abandoned] or ![superseded] labels depending on which is more suitable. These `experiment: abandoned` or `experiment: superseded` labels depending on which is
experiments will be removed from Task. more suitable. These experiments will be removed from Task.
<!-- prettier-ignore-start -->
[proposal]: https://img.shields.io/badge/experiment:%20proposal-purple
[draft]: https://img.shields.io/badge/experiment:%20draft-purple
[candidate]: https://img.shields.io/badge/experiment:%20candidate-purple
[stable]: https://img.shields.io/badge/experiment:%20stable-purple
[released]: https://img.shields.io/badge/experiment:%20released-purple
[abandoned]: https://img.shields.io/badge/experiment:%20abandoned-purple
[superseded]: https://img.shields.io/badge/experiment:%20superseded-purple
<!-- prettier-ignore-end -->