Description
This issue is intended to be a holding place for everything related to the idea of "feature flags" to unblock writing documentation for upcoming Editions - specifically Polaris.
Summary of the problem
As part of our last Edition (Octane) we started a long-running branch that was open for almost a year. This branch was challenging to keep up to date and we needed to constantly merge our work between main and our branch to make sure that updates were not lost over the course of that year. Learning from the challenges of maintaining that long-running branch we propose that we implement a feature-flag strategy for the up-coming Edition Polaris.
Motivation of feature flags
If we use a feature-flag strategy we can merge any updates to the documentation straight to the main branch without needing to keep a long-running branch up to date. It will also mean that the production deployment of the guides will be the same place that you will be able to see the "Polaris preview guides" by toggling a flag that says you want to see the preview guides. When Polaris becomes the released Edition then the process of releasing is to just delete the feature flag for that version of the guides 👍
Requirements
- We need to be able to define the feature flags that are available to toggle on a version-by version basis. i.e. before version 5.9 we don't have any Polaris documentation so there should be no UI element displayed to toggle feature flags
- we will likely want to support the idea of "sub flags" e.g. as Typescript is a Pillar of Polaris we will likely want to allow people to read our documentation with the examples in Typescript and include any descriptive blocks related to just typescript. But the toggle for typescript docs will only be available after you have first toggled the polaris docs
- we will also probably need to write a simple linting system to make sure that sub-flag marked content is only contained inside its parent sections
- we don't want to complicate the authoring format of the markdown. The guides are written using guidemaker which has an explicit design requirement of being easy to use for documentation writers. If we need an overly complicated structure of docs to achieve feature flagging then this project will be considered a failure
- @IgnaceMaes has proposed that we copy Vue's docs by wrapping flagged content in a div with the right class and we can then toggle them. This is a perfect solution as long as we continue to use a markdown renderer that follows the Commonmark standard of rendering markdown that is surrounded by HTML elements 👍
- this needs to be structured in some way, if we use classes then we need to make sure the flag classes have the same prefix so we can lint that you're only using flags that the current version of the docs supports. We could consider using
data-flag="something"structure so we don't use classes to define structure but this could be discussed and decided upon later
- any solution that we use must not affect SEO in any way. This means that we need to make sure that there is a default implementation that works in SSG/pre-rendering so that the description field remains correct to bots
Example
To clarify some of the specifics of the above, I want to provide an example of a feature flag and a sub-flag that we are currently contemplating adding to the guides.
We want to add the polaris feature flag that will allow us to start writing preview documentation for the upcoming Polaris edition. One of the "Pillars of Polaris" is full native Typescript support, but we don't want to force people to use typescript if they don't want to so we want to provide a toggle that can switch between Javascript and Typescript.
So starting with the current version (5.10) we want people to see a toggle for Polaris preview docs, but we will not show them the toggle for Typescript until after they have picked Polaris preview docs.
This also means that anyone viewing the previous guides version(s) will not see the toggle for Polaris preview docs and won't be able to view any of the docs in Typescript.
The version after Polaris is made the default edition (e.g. 6.8) you will no longer be able to switch to the Octane version of the docs, and the Typescript toggle will remain. At this point the typescript feature-flag is no longer going to be a "sub-flag" and will essentially be "promoted" to a top-level flag.
Markdown example for guides version with Polaris preview e.g. 5.10
Here is a concept that is common to both Octane and Polaris
<div data-flag="polaris">
... and here is where we add to that concept in the polaris docs
<div data-flag="typescript">
... with some extra data in typescript only docs
</div>
<div data-flag="javascript">
and maybe we could talk about loosey goosy JS here
</div>
</div>
<!-- <div data-flag="typescript">
this is ilegal 🚓
</div> -->
<div data-flag="octane">
this whole concept is deleted in polaris so we don't need to explain it any more
</div>Markdown example for guides version after Polaris is the default e.g. 6.10 (guessing)
Here is a concept that is common to both Octane and Polaris
... and here is where we add to that concept in the polaris docs
<div data-flag="typescript">
... with some extra data in typescript only docs
</div>
<div data-flag="javascript">
and maybe we could talk about loosey goosy JS here
</div>
<!-- octane one deleted -->Process
Once there is broad agreement on this plan among the core teams we will start putting together more concrete tasks on how to make this plan happen. This issue will either become a series of tasks in a list or it will link to a project that will keep track of the work 👍