diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md index 4e5a82e5dc..29b86bc63b 100644 --- a/docs/docs/contributing.md +++ b/docs/docs/contributing.md @@ -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 diff --git a/docs/docs/experiments/experiments.md b/docs/docs/experiments/experiments.md index 8498766ad2..ff2c69f6bf 100644 --- a/docs/docs/experiments/experiments.md +++ b/docs/docs/experiments/experiments.md @@ -27,8 +27,7 @@ You can enable an experimental feature by: 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]. +Flags will always override environment variables. ## Current Experimental Features and Deprecations diff --git a/docs/docs/experiments/workflow.md b/docs/docs/experiments/workflow.md new file mode 100644 index 0000000000..ec778ff7b3 --- /dev/null +++ b/docs/docs/experiments/workflow.md @@ -0,0 +1,84 @@ +--- +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 / Superseeded + +If an experiment is unsuccessful at any point then it will be given the +![abandoned] or ![superseeded] 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 +[superseeded]: https://img.shields.io/badge/experiment:%20superseeded-purple +