diff options
Diffstat (limited to 'doc/development/documentation/feature_flags.md')
| -rw-r--r-- | doc/development/documentation/feature_flags.md | 74 |
1 files changed, 52 insertions, 22 deletions
diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 37be2178592..854faa839ef 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -7,33 +7,32 @@ description: "GitLab development - how to document features deployed behind feat # Document features deployed behind feature flags -GitLab uses [feature flags](../feature_flags/index.md) to strategically roll -out the deployment of its own features. The way we document a feature behind a -feature flag depends on its state (enabled or disabled). When the state -changes, the developer who made the change **must update the documentation** -accordingly. +GitLab uses [feature flags](../feature_flags/index.md) to roll +out the deployment of its own features. + +When the state of a feature flag changes, the developer who made the change +**must update the documentation**. ## When to document features behind a feature flag Every feature introduced to the codebase, even if it's behind a disabled feature flag, must be documented. For more information, see -[the discussion that led to this decision](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). +[the discussion that led to this decision](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47917#note_459984428). [Experiment or Beta](../../policy/alpha-beta-support.md) features are usually behind a feature flag, and must also be documented. For more information, see [Document Experiment or Beta features](alpha_beta.md). + +When the feature is [implemented in multiple merge requests](../feature_flags/index.md#feature-flags-in-gitlab-development), +discuss the plan with your technical writer. -When the feature is [implemented over multiple merge requests](../feature_flags/index.md#feature-flags-in-gitlab-development), -discuss the exact documentation plan with your technical writer. Consider -creating a dedicated documentation issue if the feature: +You can create a documentation issue and delay the documentation if the feature: - Is far-reaching (makes changes across many areas of GitLab), like navigation changes. - Includes many MRs. - Affects more than a few documentation pages. - Is not fully functional if the feature flag is enabled for testing. -If you and the technical writer agree to delay the product documentation (for example, until after testing), -collaborate with the TW to create a documentation issue detailing the plan for adding the content. -The PM and EM should be included in the discussions to make sure the task of adding the documentation is assigned and scheduled. -Despite any planned delays, every feature flag in the codebase is automatically listed at -<https://docs.gitlab.com/ee/user/feature_flags.html#available-feature-flags>, -even when the feature is not fully functional. +The PM, EM, and writer should make sure the documentation work is assigned and scheduled. + +Every feature flag in the codebase is [in the documentation](../../user/feature_flags.md), +even when the feature is not fully functional or otherwise documented. ## How to add feature flag documentation @@ -57,13 +56,6 @@ Possible version history entries are: > - [Generally available](issue-link) in GitLab X.Y. Feature flag `flag_name` removed. ``` -You can combine entries if they happened in the same release: - -```markdown -> - Introduced in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/337507) in GitLab 14.3. -``` - ## Use a note to describe the state of the feature flag Information about feature flags should be in a `FLAG` note at the start of the topic (just below the version history). @@ -144,3 +136,41 @@ And, when the feature is done and fully available to all users: > - [Enabled on GitLab.com](https://gitlab.com/issue/etc) in GitLab 13.9. > - [Generally available](issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed. ``` + +## Simplify long version history + +The version history can get long, but you can sometimes simplify or remove entries. + +Combine entries if they happened in the same release: + +- Before: + + ```markdown + > - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. + > - [Enabled on GitLab.com](issue-link) in GitLab 14.3. + > - [Enabled on self-managed](issue-link) in GitLab 14.3. + ``` + +- After: + + ```markdown + > - [Introduced](issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default. + > - [Enabled on GitLab.com and self-managed](issue-link) in GitLab 14.3. + ``` + +Remove `Enabled on GitLab.com` entries when the feature is enabled by default for both GitLab.com and self-managed: + +- Before: + + ```markdown + > - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default. + > - [Enabled on GitLab.com](issue-link) in GitLab 15.9. + > - [Generally available](issue-link) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed. + ``` + +- After: + + ```markdown + > - [Introduced](issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default. + > - [Generally available](issue-link) in GitLab 15.10. Feature flag `ci_hooks_pre_get_sources_script` removed. + ``` |