Quest: Feature flags for upcoming Edition features

[mansona]

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 👍

[jaredgalanis]

I do understand the plan and agree with it 👍. I also do think it represents what we discussed on 6/17.

[IgnaceMaes]

Overall this looks like a good way forward!

Some thoughts:

• Agree we need to limit the nesting of flags, as otherwise it will get too complex to manage.
• I'm a fan of the data-flag attribute (or similar) approach compared to using classes (but that's an implementation detail)
• I don't think TypeScript really follows the same story as other new features in the way that it doesn't replace something else, so I don't think it should be a feature flag. And as long as Ember officially supports JS and TS, we need to support both. Making it use the same authoring format is probably good though. So it's more the way of visualizing the toggle where the detail really matters. (which might be seen as implementation detail as well?)

Update: we discussed it again during the Learning core team meeting and clarified the issue. Sounds good to me 👍

[NullVoxPopuli]

Will feature flags be in query params -- so that we can link to specific areas with flags enabled/disabled? (I think we should!)

[kategengler]

I agree with @IgnaceMaes -- I prefer the data-flag attribute as it would be easy to search and clean up old areas.

I also agree that TS examples are different than a feature flag since it would be a feature flag that lived forever.

[mansona]

@kategengler I added the examples to explain what will happen with Typescript. We probably need to not call these things "feature flags" in the code because it is implying that they will get deleted eventually. TS is a "sub-flag" in my example.

Looking at the examples does it work the way that you expect it to?

[kategengler]

I think the examples are fine but I do think you have two different concepts, even if they may share implementation details. One is for a long-lived feature of the guides to toggle between different types of examples (TS vs JS) and another is feature flags which are expected to be deleted eventually.

[kategengler]

Ed and I started thinking about actually writing documentation under this scheme -- we found that it is a bit awkward because each flag needs an on and and and off state. For example, If updating the Quick Start for template tag, we'd need to fence both the old hbs way and the new template-tag way.