Skip to content

Commit c108fe3

Browse files
pd93pd93
committed
docs: add experiements doc and v2 deprecation notice
1 parent 794de91 commit c108fe3

11 files changed

+84
-10
lines changed

‎docs/docs/changelog.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /changelog/
3-
sidebar_position: 8
3+
sidebar_position: 9
44
---
55

66
# Changelog

‎docs/docs/community.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /community/
3-
sidebar_position: 9
3+
sidebar_position: 10
44
---
55

66
# Community

‎docs/docs/contributing.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /contributing/
3-
sidebar_position: 10
3+
sidebar_position: 11
44
---
55

66
# Contributing

‎docs/docs/donate.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /donate/
3-
sidebar_position: 13
3+
sidebar_position: 15
44
---
55

66
# Donate

‎docs/docs/experiments.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
slug: /experiments/
3+
sidebar_position: 5
4+
---
5+
6+
# Experiments
7+
8+
:::caution
9+
10+
All experimental features are subject to breaking changes and/or removal _at any
11+
time_. We strongly recommend that you do not use these features in a production
12+
environment. They are intended for testing and feedback only.
13+
14+
:::
15+
16+
In order to allow Task to evolve quickly, we roll out breaking changes to minor
17+
versions behind experimental flags. This allows us to gather feedback on
18+
breaking changes before committing to a major release. This document describes
19+
the current set of experimental features and the deprecated feature that they
20+
are intended to replace.
21+
22+
You can enable an experimental feature by:
23+
24+
1. Using the `--x-<feature>` flag. This is intended for one-off invocations of
25+
Task to test out experimental features. You can also disable a feature by
26+
specifying a falsy value such as `--x-<feature>=false`.
27+
1. Using the `TASK_X_<FEATURE>=1` environment variable. This is intended for
28+
permanently enabling experimental features in your environment.
29+
30+
You can view the [full breaking changes proposal on
31+
GitHub][breaking-change-proposal].
32+
33+
## Current Experimental Features and Deprecations
34+
35+
Each section below details an experiment or deprecation and explains what the
36+
flags/environment variables to enable the experiment are and how the feature's
37+
behavior will change. It will also explain what you need to do to migrate any
38+
existing Taskfiles to the new behavior.
39+
40+
<!-- EXPERIMENT TEMPLATE - Include sections as necessary...
41+
42+
### ![experiment] <Feature> ([#<issue>](https://github.com/go-task/task/issues/<issue>)), ...)
43+
44+
- Flag to enable: `--x-<feature>`
45+
- Env to enable: `TASK_X_<feature>`
46+
- Deprecates: <list any existing functionality that will be deprecated by this experiment>
47+
48+
<Short description of the feature>
49+
50+
<Short explanation of how users should migrate to the new behavior>
51+
52+
-->
53+
54+
### ![deprecated] Version 2 Schema ([#1197][deprecate-version-2-schema])
55+
56+
The Taskfile v2 schema was introduced in March 2018 and replaced by version 3 in
57+
August the following year. Users have had a long time to update and so we feel
58+
that it is time to tidy up the codebase and focus on new functionality instead.
59+
60+
This notice does not mean that we are immediately removing support for version 2
61+
schemas. However, support will not be extended to future major releases and we
62+
_strongly recommend_ that anybody still using a version 2 schema upgrades to
63+
version 3 as soon as possible.
64+
65+
A list of changes between version 2 and version 3 are available in the [Task v3
66+
Release Notes][version-3-release-notes].
67+
68+
<!-- prettier-ignore-start -->
69+
[breaking-change-proposal]: https://github.com/go-task/task/discussions/1191
70+
[deprecate-version-2-schema]: https://github.com/go-task/task/issues/1197
71+
[version-3-release-notes]: https://github.com/go-task/task/releases/tag/v3.0.0
72+
[deprecated]: https://img.shields.io/badge/deprecated-red
73+
[experiment]: https://img.shields.io/badge/experiment-yellow
74+
<!-- prettier-ignore-end -->

‎docs/docs/faq.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /faq/
3-
sidebar_position: 6
3+
sidebar_position: 7
44
---
55

66
# FAQ

‎docs/docs/integrations.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /integrations/
3-
sidebar_position: 5
3+
sidebar_position: 6
44
---
55

66
# Integrations

‎docs/docs/releasing.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /releasing/
3-
sidebar_position: 11
3+
sidebar_position: 13
44
---
55

66
# Releasing

‎docs/docs/styleguide.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /styleguide/
3-
sidebar_position: 7
3+
sidebar_position: 8
44
---
55

66
# Styleguide

‎docs/docs/taskfile_versions.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /taskfile-versions/
3-
sidebar_position: 12
3+
sidebar_position: 14
44
---
55

66
# Taskfile Versions

‎docs/docs/translate.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
slug: /translate/
3-
sidebar_position: 14
3+
sidebar_position: 12
44
---
55

66
# Translate

0 commit comments

Comments
 (0)