2017-08-24 03:49:00 +00:00
# Feature Flagging
2017-08-24 03:59:36 +00:00
To ensure Desktop along without being blocked on design feedback, we need a way
to be able to ship features that are stable but not necessarily ready for
2018-02-01 23:08:53 +00:00
general usage. This document outlines what we should flag and how to flag
these features.
2017-08-24 03:49:00 +00:00
## What Should Be Feature Flagged?
2017-08-24 03:59:36 +00:00
A **preview feature** can be considered as:
2017-08-24 03:49:00 +00:00
2018-02-01 23:08:53 +00:00
- something that has a well-defined scope
- a consensus exists that the team is happy to proceed, but
- some details need to be thought through or clarified
2017-08-24 03:49:00 +00:00
2017-08-24 03:59:36 +00:00
We're currently focused on user interface changes - new views, significant
2018-02-01 23:08:53 +00:00
changes to existing views, and so on. We can revisit this list when we
identify other cases where this sort of feature flagging needs to occur.
2017-08-24 03:49:00 +00:00
2017-11-15 21:00:38 +00:00
A **beta feature** should be:
2018-02-01 23:08:53 +00:00
- a feature that is slated for an upcoming release, and
- is usably complete, but
- needs more testing, or
- needs to be used to see how it feels
2017-11-15 21:00:38 +00:00
Beta features are a superset of preview features.
2017-08-24 03:49:00 +00:00
## Why not just ship it?
A few reasons:
2018-02-01 23:08:53 +00:00
- some solutions just need time to appear, and this lets us get working code
out quicker.
- we want to get feedback easily - users can opt-in to these preview features.
- we want to be conservative with evolving the UI - most users aren't fans of
frequent, unnecessary churn.
- if we don't like something we can pull it before people get too attached to
it.
2017-08-24 03:49:00 +00:00
## How to Feature Flag?
2019-12-23 06:07:02 +00:00
First add a new function to [feature-flag.ts ](https://github.com/desktop/desktop/blob/3ee29eb1bd083a53f69fdbec2e2b10ec93404e44/app/src/lib/feature-flag.ts#L30 ). The function should usually check `enableDevelopmentFeatures()` or `enableBetaFeatures()` . Then, at runtime, your code should check your feature flag function and either display the new feature or the existing one.
2017-11-20 14:44:09 +00:00
2018-02-01 23:08:53 +00:00
See pull request integration in [#3339 ](https://github.com/desktop/desktop/pull/3339 ) for an example.
2017-08-24 03:49:00 +00:00
2017-08-24 03:59:36 +00:00
This separation and naming scheme makes it easier to clean up the new or old
feature once things are stabilized.
2017-08-24 03:49:00 +00:00
## How to test
2018-02-15 16:56:11 +00:00
**Opting-in for preview features**
2018-04-10 15:06:42 +00:00
1. Set the `GITHUB_DESKTOP_PREVIEW_FEATURES` environment variable to `1`
2018-02-15 16:56:11 +00:00
1. Restart GitHub Desktop
2018-02-15 02:51:59 +00:00
2018-04-10 15:06:42 +00:00
Don't have that environment variable?
2018-02-15 02:57:43 +00:00
No worries, simply create it. (here's a [handy guide ](https://www.schrodinger.com/kb/1842 ) for doing that on most major OSs).
2018-02-15 02:51:59 +00:00
2018-02-15 16:56:11 +00:00
**Opting-out for preview features**
1. Remove the `GITHUB_DESKTOP_PREVIEW_FEATURES` environment variable
1. Restart GitHub Desktop
