mirror of
https://github.com/go-task/task.git
synced 2025-03-17 21:08:01 +02:00
chore: update experiments and deprecation docs (#1315)
This commit is contained in:
Pete Davison
GitHub
parent
3f2abe011b
commit
a207289955
@ -1,6 +1,6 @@
|
||||
---
|
||||
slug: /changelog/
|
||||
sidebar_position: 9
|
||||
sidebar_position: 14
|
||||
---
|
||||
|
||||
# Changelog
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
slug: /community/
|
||||
sidebar_position: 10
|
||||
sidebar_position: 9
|
||||
---
|
||||
|
||||
# Community
|
||||
@ -11,7 +11,8 @@ thankful for everyone that helps me to improve the overall experience.
|
||||
|
||||
## Translations
|
||||
|
||||
We use [Crowdin](https://crowdin.com/project/taskfile) to translate our document.
|
||||
We use [Crowdin](https://crowdin.com/project/taskfile) to translate our
|
||||
document.
|
||||
|
||||
## Integrations
|
||||
|
||||
|
||||
19
docs/docs/deprecations/deprecations.md
Normal file
19
docs/docs/deprecations/deprecations.md
Normal file
@ -0,0 +1,19 @@
|
||||
---
|
||||
slug: /deprecations/
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
# Deprecations
|
||||
|
||||
As Task evolves, it occasionally outgrows some of its functionality. This can be
|
||||
because they are no longer useful, because another feature has replaced it or
|
||||
because of a change in the way that Task works internally.
|
||||
|
||||
When this happens, we mark the functionality as deprecated. This means that it
|
||||
will be removed in a future version of Task. This functionality will continue to
|
||||
work until that time, but we strongly recommend that you do not implement this
|
||||
functionality in new Taskfiles and make a plan to migrate away from it as soon
|
||||
as possible.
|
||||
|
||||
You can view a full list of active deprecations in the "Deprecations" section of
|
||||
the sidebar.
|
||||
18
docs/docs/deprecations/template.md
Normal file
18
docs/docs/deprecations/template.md
Normal file
@ -0,0 +1,18 @@
|
||||
---
|
||||
# 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 Deprecated Feature}
|
||||
|
||||
- Issue: [#{issue}](https://github.com/go-task/task/issues/{issue})
|
||||
- Breaks:
|
||||
- {list any existing functionality that will be broken by this experiment}
|
||||
|
||||
{Short description of the feature/behavior and why it is being deprecated}
|
||||
|
||||
{Short explanation of any replacement features/behaviors and how users should
|
||||
migrate to it}
|
||||
27
docs/docs/deprecations/version_2_schema.md
Normal file
27
docs/docs/deprecations/version_2_schema.md
Normal file
@ -0,0 +1,27 @@
|
||||
---
|
||||
slug: /deprecations/version-2-schema/
|
||||
---
|
||||
|
||||
# Version 2 Schema
|
||||
|
||||
- Issue: [#1197][deprecate-version-2-schema]
|
||||
- Breaks:
|
||||
- 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
|
||||
that it is time to tidy up the codebase and focus on new functionality instead.
|
||||
|
||||
This notice does not mean that we are immediately removing support for version 2
|
||||
schemas. However, support will not be extended to future major releases and we
|
||||
_strongly recommend_ that anybody still using a version 2 schema upgrades to
|
||||
version 3 as soon as possible.
|
||||
|
||||
A list of changes between version 2 and version 3 are available in the [Task v3
|
||||
Release Notes][version-3-release-notes].
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
[deprecate-version-2-schema]: https://github.com/go-task/task/issues/1197
|
||||
[version-3-release-notes]: https://github.com/go-task/task/releases/tag/v3.0.0
|
||||
<!-- prettier-ignore-end -->
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
slug: /donate/
|
||||
sidebar_position: 15
|
||||
sidebar_position: 16
|
||||
---
|
||||
|
||||
# Donate
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
slug: /experiments/
|
||||
sidebar_position: 5
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# Experiments
|
||||
@ -16,8 +16,11 @@ environment. They are intended for testing and feedback only.
|
||||
In order to allow Task to evolve quickly, we 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 document describes
|
||||
the current set of experimental features and the deprecated feature that they
|
||||
are intended to replace.
|
||||
the current set of experimental features and their status in the
|
||||
[workflow](#workflow).
|
||||
|
||||
You can view a full list of active experiments in the "Experiments" section of
|
||||
the sidebar.
|
||||
|
||||
You can enable an experimental feature by:
|
||||
|
||||
@ -42,59 +45,83 @@ 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.
|
||||
|
||||
<!-- EXPERIMENT TEMPLATE - Include sections as necessary...
|
||||
## Workflow
|
||||
|
||||
### ![experiment] {Feature} ([#{issue}](https://github.com/go-task/task/issues/{issue})), ...)
|
||||
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.
|
||||
|
||||
- Environment variable: `TASK_X_{feature}`
|
||||
- Deprecates: {list any existing functionality that will be deprecated by this experiment}
|
||||
- Breaks: {list any existing functionality that will be broken by this experiment}
|
||||
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.
|
||||
|
||||
{Short description of the feature}
|
||||
### 1. Proposal
|
||||
|
||||
{Short explanation of how users should migrate to the new behavior}
|
||||
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 ![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
|
||||
|
||||
### ![deprecated] Version 2 Schema ([#1197][deprecate-version-2-schema])
|
||||
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 ![draft] label. This indicates that an
|
||||
implementation is now available for use in a release and the experiment is open
|
||||
for feedback.
|
||||
|
||||
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
|
||||
that it is time to tidy up the codebase and focus on new functionality instead.
|
||||
:::note
|
||||
|
||||
This notice does not mean that we are immediately removing support for version 2
|
||||
schemas. However, support will not be extended to future major releases and we
|
||||
_strongly recommend_ that anybody still using a version 2 schema upgrades to
|
||||
version 3 as soon as possible.
|
||||
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_.
|
||||
|
||||
A list of changes between version 2 and version 3 are available in the [Task v3
|
||||
Release Notes][version-3-release-notes].
|
||||
:::
|
||||
|
||||
### ![experiment] Gentle Force ([#1200](https://github.com/go-task/task/issues/1200))
|
||||
### 3. Candidate
|
||||
|
||||
- Environment variable: `TASK_X_FORCE=1`
|
||||
- Breaks: `--force` flag
|
||||
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 ![candidate] label. This indicates that a proposal is _likely_ to accepted
|
||||
and will enter a period for final comments and minor changes.
|
||||
|
||||
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.
|
||||
### 4. Stable
|
||||
|
||||
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.
|
||||
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
|
||||
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.
|
||||
|
||||
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!
|
||||
### 5. Released
|
||||
|
||||
When making a new major release of Task, all experiments marked as ![stable]
|
||||
will move to ![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
|
||||
![abandoned] or ![superseded] labels depending on which is more suitable. These
|
||||
experiments will be removed from Task.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
[breaking-change-proposal]: https://github.com/go-task/task/discussions/1191
|
||||
[deprecate-version-2-schema]: https://github.com/go-task/task/issues/1197
|
||||
[version-3-release-notes]: https://github.com/go-task/task/releases/tag/v3.0.0
|
||||
[deprecated]: https://img.shields.io/badge/deprecated-red
|
||||
[experiment]: https://img.shields.io/badge/experiment-yellow
|
||||
[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 -->
|
||||
|
||||
30
docs/docs/experiments/gentle_force.md
Normal file
30
docs/docs/experiments/gentle_force.md
Normal file
@ -0,0 +1,30 @@
|
||||
---
|
||||
slug: /experiments/gentle-force/
|
||||
---
|
||||
|
||||
# Gentle Force
|
||||
|
||||
- Issue: [#1200][gentle-force-experiment]
|
||||
- Environment variable: `TASK_X_FORCE=1`
|
||||
- Breaks:
|
||||
- `--force` flag
|
||||
|
||||
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 -->
|
||||
[gentle-force-experiment]: https://github.com/go-task/task/issues/1200
|
||||
<!-- prettier-ignore-end -->
|
||||
20
docs/docs/experiments/template.md
Normal file
20
docs/docs/experiments/template.md
Normal file
@ -0,0 +1,20 @@
|
||||
---
|
||||
# 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: [#{issue}](https://github.com/go-task/task/issues/{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}
|
||||
|
||||
{Short description of the feature}
|
||||
|
||||
{Short explanation of how users should migrate to the new behavior}
|
||||
@ -1,84 +0,0 @@
|
||||
---
|
||||
slug: /experiments/workflow/
|
||||
---
|
||||
|
||||
# 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 ![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 ![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 ![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 ![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 ![stable]
|
||||
will move to ![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
|
||||
![abandoned] or ![superseded] labels depending on which is 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 -->
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
slug: /faq/
|
||||
sidebar_position: 7
|
||||
sidebar_position: 15
|
||||
---
|
||||
|
||||
# FAQ
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
slug: /integrations/
|
||||
sidebar_position: 6
|
||||
sidebar_position: 8
|
||||
---
|
||||
|
||||
# Integrations
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
slug: /styleguide/
|
||||
sidebar_position: 8
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
# Styleguide
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
slug: /taskfile-versions/
|
||||
sidebar_position: 14
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Taskfile Versions
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user