docs: add file for users to see status of feature flags (#13402)

* add file for users to see status of feature flags * move comment * update flags per feedback * move to subfolder and improve docs * move CODE_OF_CONDUCT to root
2021-03-16 14:11:17 -07:00 · 2021-03-16 14:11:17 -07:00 · bf424e3351
parent 21cc49509f
commit bf424e3351
9 changed files with 83 additions and 26 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -578,6 +578,8 @@ export enum FeatureFlag {
 those specified under FEATURE_FLAGS in `superset_config.py`. For example, `DEFAULT_FEATURE_FLAGS = { 'FOO': True, 'BAR': False }` in `superset/config.py` and `FEATURE_FLAGS = { 'BAR': True, 'BAZ': True }` in `superset_config.py` will result
 in combined feature flags of `{ 'FOO': True, 'BAR': True, 'BAZ': True }`.

+The current status of the usability of each flag (stable vs testing, etc) can be found in `RESOURCES/FEATURE_FLAGS.md`.
+
 ## Git Hooks

 Superset uses Git pre-commit hooks courtesy of [pre-commit](https://pre-commit.com/). To install run the following:
--- a/README.md
+++ b/README.md
@ -45,7 +45,7 @@ A modern, enterprise-ready business intelligence web application.
 [**Get Involved**](#get-involved) |
 [**Contributor Guide**](#contributor-guide) |
 [**Resources**](#resources) |
-[**Organizations Using Superset**](INTHEWILD.md)
+[**Organizations Using Superset**](RESOURCES/INTHEWILD.md)


 ## Screenshots & Gifs
@ -140,7 +140,7 @@ Want to add support for your datastore or data engine? Read more [here](https://

 * Ask and answer questions on [StackOverflow](https://stackoverflow.com/questions/tagged/apache-superset) using the **apache-superset** tag
 * [Join our community's Slack](https://join.slack.com/t/apache-superset/shared_invite/zt-l5f5e0av-fyYu8tlfdqbMdz_sPLwUqQ)
-  and please read our [Slack Community Guidelines](CODE_OF_CONDUCT.md#slack-community-guidelines)
+  and please read our [Slack Community Guidelines](https://github.com/apache/superset/blob/master/CODE_OF_CONDUCT.md#slack-community-guidelines)
 * [Join our dev@superset.apache.org Mailing list](https://lists.apache.org/list.html?dev@superset.apache.org)


--- a/RESOURCES/FEATURE_FLAGS.md
+++ b/RESOURCES/FEATURE_FLAGS.md
@ -0,0 +1,65 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Superset Feature Flags
+This is a list of the current Superset optional features. See config.py for default values. These features can be turned on/off by setting your preferred values in superset_config.py to True/False respectively
+
+## In Development
+These features are considered **unfinished** and should only be used on development environments.
+
+- CLIENT_CACHE
+- DASHBOARD_CACHE
+- DASHBOARD_NATIVE_FILTERS_SET
+- DASHBOARD_RBAC
+- DISABLE_DATASET_SOURCE_EDIT
+- ENABLE_EXPLORE_JSON_CSRF_PROTECTION
+- KV_STORE
+- PRESTO_EXPAND_DATA
+- REMOVE_SLICE_LEVEL_LABEL_COLORS
+- SHARE_QUERIES_VIA_KV_STORE
+- TAGGING_SYSTEM
+
+## In Testing
+These features are **finished** but currently being tested. They are usable, but may still contain some bugs.
+
+- ALERT_REPORTS: [(docs)](https://superset.apache.org/docs/installation/alerts-reports)
+- DYNAMIC_PLUGINS: [(docs)](https://superset.apache.org/docs/installation/running-on-kubernetes)
+- DASHBOARD_NATIVE_FILTERS
+- GLOBAL_ASYNC_QUERIES [(docs)](https://github.com/apache/superset/blob/master/CONTRIBUTING.md#async-chart-queries)
+- OMNIBAR
+- VERSIONED_EXPORT
+
+## Stable
+These features flags are **safe for production** and have been tested.
+
+- DASHBOARD_CROSS_FILTERS
+- ESCAPE_MARKDOWN_HTML
+- ENABLE_TEMPLATE_PROCESSING
+- LISTVIEWS_DEFAULT_CARD_VIEW
+- ROW_LEVEL_SECURITY
+- SCHEDULED_QUERIES [(docs)](https://superset.apache.org/docs/installation/alerts-reports)
+- SQL_VALIDATORS_BY_ENGINE [(docs)](https://superset.apache.org/docs/installation/sql-templating)
+- SQLLAB_BACKEND_PERSISTENCE
+- THUMBNAILS [(docs)](https://superset.apache.org/docs/installation/cache)
+
+## Deprecated Flags
+These features flags currently default to True and **will be removed in a future major release**. For this current release you can turn them off by setting your config to False, but it is advised to remove or set these flags in your local configuration to **True** so that you do not experience any unexpected changes in a future release.
+
+- ALLOW_DASHBOARD_DOMAIN_SHARDING
+- DISPLAY_MARKDOWN_HTML
+- ENABLE_REACT_CRUD_VIEWS
--- a/RESOURCES/INTHEWILD.md
+++ b/RESOURCES/INTHEWILD.md
--- a/docs/installation.rst
+++ b/docs/installation.rst
@ -1575,17 +1575,7 @@ You can enable or disable features with flag from ``superset_config.py``:
         'PRESTO_EXPAND_DATA': False,
     }

-Here is a list of flags and descriptions:
-
-* ENABLE_EXPLORE_JSON_CSRF_PROTECTION
-
-  * For some security concerns, you may need to enforce CSRF protection on all query request to explore_json endpoint. In Superset, we use `flask-csrf <https://sjl.bitbucket.io/flask-csrf/>`_ add csrf protection for all POST requests, but this protection doesn't apply to GET method.
-
-  * When ENABLE_EXPLORE_JSON_CSRF_PROTECTION is set to true, your users cannot make GET request to explore_json. The default value for this feature False (current behavior), explore_json accepts both GET and POST request. See `PR 7935 <https://github.com/apache/superset/pull/7935>`_ for more details.
-
-* PRESTO_EXPAND_DATA
-
-  * When this feature is enabled, nested types in Presto will be expanded into extra columns and/or arrays. This is experimental, and doesn't work with all nested types.
+A current list of feature flags can be found in `RESOURCES/FEATURE_FLAGS.md`


 SIP-15
--- a/docs/src/pages/community.tsx
+++ b/docs/src/pages/community.tsx
@ -51,7 +51,7 @@ const links = [
    'join our monthly virtual meetups and register for any upcoming events',
  ],
  [
-    'https://github.com/apache/superset/blob/master/INTHEWILD.md',
+    'https://github.com/apache/superset/blob/master/RESOURCES/INTHEWILD.md',
    'Organizations',
    'a list of some of the organizations using Superset in production',
  ],
--- a/docs/src/pages/docs/installation/configuring.mdx
+++ b/docs/src/pages/docs/installation/configuring.mdx
@ -192,17 +192,7 @@ DEFAULT_FEATURE_FLAGS = {
 }
 ```

-Here is a list of flags and descriptions:
-
- `ENABLE_EXPLORE_JSON_CSRF_PROTECTION`: For some security concerns, you may need to enforce CSRF
-  protection on all query request to the `explore_json` endpoint. When
-  `ENABLE_EXPLORE_JSON_CSRF_PROTECTION` is set to true, your users cannot make GET request to
-  `explore_json`. The default value for this feature is `False` and `explore_json` will accept both
-  GET and POST request. See [PR 7935](https://github.com/apache/superset/pull/7935) for
-  more details.
-
- `PRESTO_EXPAND_DATA`: When this feature is enabled, nested types in Presto will be expanded into
-  extra columns and / or arrays. This is experimental, and doesn’t work with all nested types.
+A current list of feature flags can be found in `RESOURCES/FEATURE_FLAGS.md`

 ### SIP 15

--- a/docs/src/pages/docs/introduction.mdx
+++ b/docs/src/pages/docs/introduction.mdx
@ -56,4 +56,4 @@ production environment inside Kubernetes and serves 600+ daily active users view
 a day.

 You can find a partial list of industries and companies embracing Superset
-[on this page in GitHub](https://github.com/apache/superset/blob/master/INTHEWILD.md).
+[on this page in GitHub](https://github.com/apache/superset/blob/master/RESOURCES/INTHEWILD.md).
--- a/superset/config.py
+++ b/superset/config.py
@ -306,9 +306,19 @@ DEFAULT_FEATURE_FLAGS: Dict[str, bool] = {
    "CLIENT_CACHE": False,
    "DISABLE_DATASET_SOURCE_EDIT": False,
    "DYNAMIC_PLUGINS": False,
+    # For some security concerns, you may need to enforce CSRF protection on
+    # all query request to explore_json endpoint. In Superset, we use
+    # `flask-csrf <https://sjl.bitbucket.io/flask-csrf/>`_ add csrf protection
+    # for all POST requests, but this protection doesn't apply to GET method.
+    # When ENABLE_EXPLORE_JSON_CSRF_PROTECTION is set to true, your users cannot
+    # make GET request to explore_json. explore_json accepts both GET and POST request.
+    # See `PR 7935 <https://github.com/apache/superset/pull/7935>`_ for more details.
    "ENABLE_EXPLORE_JSON_CSRF_PROTECTION": False,
    "ENABLE_TEMPLATE_PROCESSING": False,
    "KV_STORE": False,
+    # When this feature is enabled, nested types in Presto will be
+    # expanded into extra columns and/or arrays. This is experimental,
+    # and doesn't work with all nested types.
    "PRESTO_EXPAND_DATA": False,
    # Exposes API endpoint to compute thumbnails
    "THUMBNAILS": False,