feat: v2 deprecation and experiments

.github/ISSUE_TEMPLATE/bug_report.md

@@ -3,13 +3,18 @@ name: Bug Report
 about: Use this to report bugs and issues
 ---
 
-> Thanks for your bug report!
->
-> Before submitting this issue, please make sure the same problem was
-> not already reported by someone else.
->
-> Please describe the bug you're facing. Consider pasting example
-> Taskfiles showing how to reproduce the problem.
+<!--
+
+Thanks for your bug report!
+
+Before submitting this issue, please make sure the same problem was not
+already reported by someone else.
+
+Please describe the bug you're facing. Consider pasting example Taskfiles
+showing how to reproduce the problem.
+
+-->
 
 - Task version:
-- Operating System:
+- Operating system:
+- Experiments enabled:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -3,9 +3,13 @@ name: Feature Request
 about: Use this to make feature requests
 ---
 
-> Describe in detail what feature do you want to see in Task.
-> Give examples if possible.
->
-> Please, search if this wasn't proposed before, and if this is more like an idea
-> than a strong feature request, consider opening a
-> [discussion](https://github.com/go-task/task/discussions) instead.
+<!--
+
+Describe in detail what feature do you want to see in Task.
+Give examples if possible.
+
+Please, search if this wasn't proposed before, and if this is more like an idea
+than a strong feature request, consider opening a
+[discussion](https://github.com/go-task/task/discussions) instead.
+
+-->

.github/workflows/issue-experiment.yml

@@ -0,0 +1,123 @@
+name: issue experiment
+
+on:
+  issues:
+    types: [labeled]
+
+jobs:
+  issue-experiment-proposed:
+    if: github.event.label.name == format('experiment{0} proposed', ':')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GH_PAT}}
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'This issue has been marked as an experiment proposal! :test_tube: It will now enter a period of consultation during which we encourage the community to provide feedback on the proposed design. Please see the [experiment workflow documentation](https://taskfile.dev/experiments/workflow) for more information on how we release experiments.'
+            })
+  issue-experiment-draft:
+    if: github.event.label.name == format('experiment{0} draft', ':')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GH_PAT}}
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'This experiment has been marked as a draft! :sparkles: This means that an initial implementation has been added to the latest release of Task! You can find information about this experiment and how to enable it in our [experiments documentation](https://taskfile.dev/experiments). Please see the [experiment workflow documentation](https://taskfile.dev/experiments/workflow) for more information on how we release experiments.'
+            })
+  issue-experiment-candidate:
+    if: github.event.label.name == format('experiment{0} candidate', ':')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GH_PAT}}
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'This experiment has been marked as a candidate! :fire: This means that the  implementation is nearing completion and we are entering a period for final comments and feedback! You can find information about this experiment and how to enable it in our [experiments documentation](https://taskfile.dev/experiments). Please see the [experiment workflow documentation](https://taskfile.dev/experiments/workflow) for more information on how we release experiments.'
+            })
+  issue-experiment-stable:
+    if: github.event.label.name == format('experiment{0} stable', ':')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GH_PAT}}
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'This experiment has been marked as stable! :metal: This means that the  implementation is now final and ready to be released. No more changes will be made and the experiment is safe to use in production! You can find information about this experiment and how to enable it in our [experiments documentation](https://taskfile.dev/experiments). Please see the [experiment workflow documentation](https://taskfile.dev/experiments/workflow) for more information on how we release experiments.'
+            })
+  issue-experiment-released:
+    if: github.event.label.name == format('experiment{0} released', ':')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GH_PAT}}
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'This experiment has been released! :rocket: This means that it is no longer an experiment and is available in the latest major version of Task. Please see the [experiment workflow documentation](https://taskfile.dev/experiments/workflow) for more information on how we release experiments.'
+            })
+            github.rest.issues.update({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'closed'
+            })
+  issue-experiment-abandoned:
+    if: github.event.label.name == format('experiment{0} abandoned', ':')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GH_PAT}}
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'This experiment has been abandoned. :disappointed: This means that this feature will not be added to Task and any experimental functionality will be removed. Please see the [experiment workflow documentation](https://taskfile.dev/experiments/workflow) for more information on how we release experiments.'
+            })
+            github.rest.issues.update({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'closed'
+            })
+  issue-experiment-superseded:
+    if: github.event.label.name == format('experiment{0} superseded', ':')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v6
+        with:
+          github-token: ${{secrets.GH_PAT}}
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'This experiment has been superseded. :seedling: This means that another experiment has replaced this one. Please see the [experiment workflow documentation](https://taskfile.dev/experiments/workflow) for more information on how we release experiments.'
+            })
+            github.rest.issues.update({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'closed'
+            })

CHANGELOG.md

@@ -2,8 +2,10 @@
 
 ## Unreleased
 
-- Only rewrite checksum files in `.task` if the checksum has changed
-  (#1185, #1194 by @deviantintegral).
+- Only rewrite checksum files in `.task` if the checksum has changed (#1185,
+  #1194 by @deviantintegral).
+- Added [experiments documentation](https://taskfile.dev/experiments) to the
+  website (#1198 by @pd93).
 
 ## v3.25.0 - 2023-05-22
 
@@ -16,7 +18,8 @@
 - Fix some errors being unintendedly supressed (#1134 by @clintmod).
 - Fix a nil pointer error when `version` is omitted from a Taskfile (#1148,
   #1149 by @pd93).
-- Fix duplicate error message when a task does not exists (#1141, #1144 by @pd93).
+- Fix duplicate error message when a task does not exists (#1141, #1144 by
+  @pd93).
 
 ## v3.24.0 - 2023-04-15
 

cmd/release/main.go

@@ -19,7 +19,7 @@ const (
 
 const changelogTemplate = `---
 slug: /changelog/
-sidebar_position: 8
+sidebar_position: 9
 ---`
 
 var (

docs/docs/changelog.md

@@ -1,6 +1,6 @@
 ---
 slug: /changelog/
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # Changelog

docs/docs/community.md

@@ -1,6 +1,6 @@
 ---
 slug: /community/
-sidebar_position: 9
+sidebar_position: 10
 ---
 
 # Community

docs/docs/contributing.md

@@ -1,6 +1,6 @@
 ---
 slug: /contributing/
-sidebar_position: 10
+sidebar_position: 11
 ---
 
 # Contributing
@@ -25,6 +25,11 @@ Studio Code][vscode-task].
   there an approach you can take that maintains this compatibility? If not,
   consider opening an issue first so that API changes can be discussed before
   you invest your time into a PR.
+- **Experiments** - If there is no way to make your change backward compatible
+  then there is a procedure to introduce breaking changes into minor versions.
+  We call these "[experiments][experiments]". If you're intending to work on an
+  experiment, then please read the [experiments workflow][experiments-workflow]
+  document carefully and submit a proposal first.
 
 ## 1. Setup
 

docs/docs/donate.md

@@ -1,6 +1,6 @@
 ---
 slug: /donate/
-sidebar_position: 13
+sidebar_position: 15
 ---
 
 # Donate

docs/docs/experiments/experiments.md

@@ -0,0 +1,73 @@
+---
+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-<feature>` 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-<feature>=false`.
+1. Using the `TASK_X_<FEATURE>=1` environment variable. This is intended for
+   permanently enabling experimental features in your environment.
+
+Flags will always override environment variables.
+
+## 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.
+
+<!-- EXPERIMENT TEMPLATE - Include sections as necessary...
+
+### ![experiment] <Feature> ([#<issue>](https://github.com/go-task/task/issues/<issue>)), ...)
+
+- Flag to enable: `--x-<feature>`
+- Env to enable: `TASK_X_<feature>`
+- Deprecates: <list any existing functionality that will be deprecated by this experiment>
+
+<Short description of the feature>
+
+<Short explanation of how users should migrate 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].
+
+<!-- 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
+<!-- prettier-ignore-end -->