From 793c1e5587650fa27fd8a087401ce52d2f4a36f0 Mon Sep 17 00:00:00 2001 From: Pete Davison Date: Wed, 31 May 2023 12:04:14 +0000 Subject: [PATCH] docs: add experiments doc and v2 deprecation notice --- cmd/release/main.go | 2 +- docs/docs/changelog.md | 2 +- docs/docs/community.md | 2 +- docs/docs/contributing.md | 2 +- docs/docs/donate.md | 2 +- docs/docs/experiments.md | 74 ++++++++++++++++++++++++++++++++++ docs/docs/faq.md | 2 +- docs/docs/integrations.md | 2 +- docs/docs/releasing.md | 2 +- docs/docs/styleguide.md | 2 +- docs/docs/taskfile_versions.md | 2 +- docs/docs/translate.md | 2 +- 12 files changed, 85 insertions(+), 11 deletions(-) create mode 100644 docs/docs/experiments.md diff --git a/cmd/release/main.go b/cmd/release/main.go index af339f5a..d0bb3ddb 100644 --- a/cmd/release/main.go +++ b/cmd/release/main.go @@ -19,7 +19,7 @@ const ( const changelogTemplate = `--- slug: /changelog/ -sidebar_position: 8 +sidebar_position: 9 ---` var ( diff --git a/docs/docs/changelog.md b/docs/docs/changelog.md index da4e08b9..42cd1eeb 100644 --- a/docs/docs/changelog.md +++ b/docs/docs/changelog.md @@ -1,6 +1,6 @@ --- slug: /changelog/ -sidebar_position: 8 +sidebar_position: 9 --- # Changelog diff --git a/docs/docs/community.md b/docs/docs/community.md index d694d548..7032b616 100644 --- a/docs/docs/community.md +++ b/docs/docs/community.md @@ -1,6 +1,6 @@ --- slug: /community/ -sidebar_position: 9 +sidebar_position: 10 --- # Community diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md index d9589e90..4e5a82e5 100644 --- a/docs/docs/contributing.md +++ b/docs/docs/contributing.md @@ -1,6 +1,6 @@ --- slug: /contributing/ -sidebar_position: 10 +sidebar_position: 11 --- # Contributing diff --git a/docs/docs/donate.md b/docs/docs/donate.md index d815a6ee..b039ef9c 100644 --- a/docs/docs/donate.md +++ b/docs/docs/donate.md @@ -1,6 +1,6 @@ --- slug: /donate/ -sidebar_position: 13 +sidebar_position: 15 --- # Donate diff --git a/docs/docs/experiments.md b/docs/docs/experiments.md new file mode 100644 index 00000000..8498766a --- /dev/null +++ b/docs/docs/experiments.md @@ -0,0 +1,74 @@ +--- +slug: /experiments/ +sidebar_position: 5 +--- + +# 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 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. + +You can enable an experimental feature by: + +1. Using the `--x-` flag. This is intended for one-off invocations of + Task to test out experimental features. You can also disable a feature by + specifying a falsy value such as `--x-=false`. +1. Using the `TASK_X_=1` environment variable. This is intended for + permanently enabling experimental features in your environment. + +You can view the [full breaking changes proposal on +GitHub][breaking-change-proposal]. + +## 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. + + + +### ![deprecated] Version 2 Schema ([#1197][deprecate-version-2-schema]) + +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]. + + +[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 + diff --git a/docs/docs/faq.md b/docs/docs/faq.md index cb37a424..db749a48 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -1,6 +1,6 @@ --- slug: /faq/ -sidebar_position: 6 +sidebar_position: 7 --- # FAQ diff --git a/docs/docs/integrations.md b/docs/docs/integrations.md index 3ab72a65..4ca8861a 100644 --- a/docs/docs/integrations.md +++ b/docs/docs/integrations.md @@ -1,6 +1,6 @@ --- slug: /integrations/ -sidebar_position: 5 +sidebar_position: 6 --- # Integrations diff --git a/docs/docs/releasing.md b/docs/docs/releasing.md index dc36d1ac..ba7bf47a 100644 --- a/docs/docs/releasing.md +++ b/docs/docs/releasing.md @@ -1,6 +1,6 @@ --- slug: /releasing/ -sidebar_position: 11 +sidebar_position: 13 --- # Releasing diff --git a/docs/docs/styleguide.md b/docs/docs/styleguide.md index b3c77cc0..fde3ec1d 100644 --- a/docs/docs/styleguide.md +++ b/docs/docs/styleguide.md @@ -1,6 +1,6 @@ --- slug: /styleguide/ -sidebar_position: 7 +sidebar_position: 8 --- # Styleguide diff --git a/docs/docs/taskfile_versions.md b/docs/docs/taskfile_versions.md index 5738d6a4..83c83705 100644 --- a/docs/docs/taskfile_versions.md +++ b/docs/docs/taskfile_versions.md @@ -1,6 +1,6 @@ --- slug: /taskfile-versions/ -sidebar_position: 12 +sidebar_position: 14 --- # Taskfile Versions diff --git a/docs/docs/translate.md b/docs/docs/translate.md index 92b409dc..47f39b35 100644 --- a/docs/docs/translate.md +++ b/docs/docs/translate.md @@ -1,6 +1,6 @@ --- slug: /translate/ -sidebar_position: 14 +sidebar_position: 12 --- # Translate