From a20728995577085b4c8a1b5b3b66ca5e24384d19 Mon Sep 17 00:00:00 2001 From: Pete Davison Date: Sat, 2 Sep 2023 15:48:05 -0500 Subject: [PATCH] chore: update experiments and deprecation docs (#1315) --- docs/docs/changelog.md | 2 +- docs/docs/community.md | 5 +- docs/docs/deprecations/deprecations.md | 19 ++++ docs/docs/deprecations/template.md | 18 ++++ docs/docs/deprecations/version_2_schema.md | 27 +++++ docs/docs/donate.md | 2 +- docs/docs/experiments/experiments.md | 111 +++++++++++++-------- docs/docs/experiments/gentle_force.md | 30 ++++++ docs/docs/experiments/template.md | 20 ++++ docs/docs/experiments/workflow.md | 84 ---------------- docs/docs/faq.md | 2 +- docs/docs/integrations.md | 2 +- docs/docs/styleguide.md | 2 +- docs/docs/taskfile_versions.md | 2 +- 14 files changed, 192 insertions(+), 134 deletions(-) create mode 100644 docs/docs/deprecations/deprecations.md create mode 100644 docs/docs/deprecations/template.md create mode 100644 docs/docs/deprecations/version_2_schema.md create mode 100644 docs/docs/experiments/gentle_force.md create mode 100644 docs/docs/experiments/template.md delete mode 100644 docs/docs/experiments/workflow.md diff --git a/docs/docs/changelog.md b/docs/docs/changelog.md index b21d0c24..0203bc3f 100644 --- a/docs/docs/changelog.md +++ b/docs/docs/changelog.md @@ -1,6 +1,6 @@ --- slug: /changelog/ -sidebar_position: 9 +sidebar_position: 14 --- # Changelog diff --git a/docs/docs/community.md b/docs/docs/community.md index 32a323ff..9505327a 100644 --- a/docs/docs/community.md +++ b/docs/docs/community.md @@ -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 diff --git a/docs/docs/deprecations/deprecations.md b/docs/docs/deprecations/deprecations.md new file mode 100644 index 00000000..aa5011a8 --- /dev/null +++ b/docs/docs/deprecations/deprecations.md @@ -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. diff --git a/docs/docs/deprecations/template.md b/docs/docs/deprecations/template.md new file mode 100644 index 00000000..4dff6e38 --- /dev/null +++ b/docs/docs/deprecations/template.md @@ -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} diff --git a/docs/docs/deprecations/version_2_schema.md b/docs/docs/deprecations/version_2_schema.md new file mode 100644 index 00000000..2eeaadcb --- /dev/null +++ b/docs/docs/deprecations/version_2_schema.md @@ -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]. + + +[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 + diff --git a/docs/docs/donate.md b/docs/docs/donate.md index b039ef9c..5a11bbab 100644 --- a/docs/docs/donate.md +++ b/docs/docs/donate.md @@ -1,6 +1,6 @@ --- slug: /donate/ -sidebar_position: 15 +sidebar_position: 16 --- # Donate diff --git a/docs/docs/experiments/experiments.md b/docs/docs/experiments/experiments.md index 64d3c6da..e26a6e31 100644 --- a/docs/docs/experiments/experiments.md +++ b/docs/docs/experiments/experiments.md @@ -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. - +### 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. -[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 diff --git a/docs/docs/experiments/gentle_force.md b/docs/docs/experiments/gentle_force.md new file mode 100644 index 00000000..aa708780 --- /dev/null +++ b/docs/docs/experiments/gentle_force.md @@ -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! + + +[gentle-force-experiment]: https://github.com/go-task/task/issues/1200 + diff --git a/docs/docs/experiments/template.md b/docs/docs/experiments/template.md new file mode 100644 index 00000000..93fc4af8 --- /dev/null +++ b/docs/docs/experiments/template.md @@ -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} diff --git a/docs/docs/experiments/workflow.md b/docs/docs/experiments/workflow.md deleted file mode 100644 index 5e1377c0..00000000 --- a/docs/docs/experiments/workflow.md +++ /dev/null @@ -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. - - -[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 - diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 9ec63141..a9dd0811 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -1,6 +1,6 @@ --- slug: /faq/ -sidebar_position: 7 +sidebar_position: 15 --- # FAQ diff --git a/docs/docs/integrations.md b/docs/docs/integrations.md index 4ca8861a..5645b891 100644 --- a/docs/docs/integrations.md +++ b/docs/docs/integrations.md @@ -1,6 +1,6 @@ --- slug: /integrations/ -sidebar_position: 6 +sidebar_position: 8 --- # Integrations diff --git a/docs/docs/styleguide.md b/docs/docs/styleguide.md index 071d952a..9017af1c 100644 --- a/docs/docs/styleguide.md +++ b/docs/docs/styleguide.md @@ -1,6 +1,6 @@ --- slug: /styleguide/ -sidebar_position: 8 +sidebar_position: 10 --- # Styleguide diff --git a/docs/docs/taskfile_versions.md b/docs/docs/taskfile_versions.md index ca6aa6d8..b6a8fa9d 100644 --- a/docs/docs/taskfile_versions.md +++ b/docs/docs/taskfile_versions.md @@ -1,6 +1,6 @@ --- slug: /taskfile-versions/ -sidebar_position: 14 +sidebar_position: 5 --- # Taskfile Versions