Merge branch 'clefelhocz1-feature-flag-policy' into 'master'

Move feature flag policy to first thing someone reads

See merge request gitlab-org/gitlab!49772

doc/development/feature_flags/index.md

@@ -6,6 +6,31 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo
 
 # Feature flags in development of GitLab
 
+## When to use feature flags
+
+Starting with GitLab 11.4, developers are required to use feature flags for
+non-trivial changes. Such changes include:
+
+- New features (e.g. a new merge request widget, epics, etc).
+- Complex performance improvements that may require additional testing in
+  production, such as rewriting complex queries.
+- Invasive changes to the user interface, such as a new navigation bar or the
+  removal of a sidebar.
+- Adding support for importing projects from a third-party service.
+- Risk of data loss
+
+In all cases, those working on the changes can best decide if a feature flag is
+necessary. For example, changing the color of a button doesn't need a feature
+flag, while changing the navigation bar definitely needs one. In case you are
+uncertain if a feature flag is necessary, simply ask about this in the merge
+request, and those reviewing the changes will likely provide you with an answer.
+
+When using a feature flag for UI elements, make sure to _also_ use a feature
+flag for the underlying backend code, if there is any. This ensures there is
+absolutely no way to use the feature until it is enabled.
+
+## How to use Feature Flags
+
 Feature flags can be used to gradually deploy changes, regardless of whether
 they are new features or performance improvements. By using feature flags,
 you can determine the impact of GitLab-directed changes, while still being able

doc/development/feature_flags/process.md

@@ -53,27 +53,6 @@ problems, such as outages.
 
 Please also read the [development guide for feature flags](development.md).
 
-### When to use feature flags
-
-Starting with GitLab 11.4, developers are required to use feature flags for
-non-trivial changes. Such changes include:
-
-- New features (e.g. a new merge request widget, epics, etc).
-- Complex performance improvements that may require additional testing in
-  production, such as rewriting complex queries.
-- Invasive changes to the user interface, such as a new navigation bar or the
-  removal of a sidebar.
-- Adding support for importing projects from a third-party service.
-
-In all cases, those working on the changes can best decide if a feature flag is
-necessary. For example, changing the color of a button doesn't need a feature
-flag, while changing the navigation bar definitely needs one. In case you are
-uncertain if a feature flag is necessary, simply ask about this in the merge
-request, and those reviewing the changes will likely provide you with an answer.
-
-When using a feature flag for UI elements, make sure to _also_ use a feature
-flag for the underlying backend code, if there is any. This ensures there is
-absolutely no way to use the feature until it is enabled.
 
 ### Including a feature behind feature flag in the final release