Docs: documenting features behind flags
Problem to solve
There have been quite a few discussions about documenting features deployed behind feature flags. We need to decide how and when to document features behind feature flags.
Current:
-
Process for creating flags. Notes:
- By default, feature flags should be off.
- Feature flags should remain in the codebase for a short period as possible to reduce the need for feature flag accounting.
- In order to build a final release and present the feature for self-managed users, the feature flag should be at least defaulted to on.
- Documenting features behind flags.
Proposal
- For feature flags disabled by default, if they cannot be used yet due to lack of completeness:
- Do not document it.
- For feature flags disabled by default, if they can be used (even in an early stage such as alpha/beta):
- Say that it's disabled by default.
- Document how to enable and disable it.
- For a feature that became enabled by default:
- Update the docs saying that it became enabled in version X.Y (link to issue/MR).
- For a feature that had the flag removed:
- Remove FF instructions.
- For a feature completely rolled back:
- Remove the docs, if any.
Question: when should we add the feature to the release post? We, TWs, can advise, but that's up to the PM, I guess?
Further details
-
Guide for GL admins describing what a FF is and how to enable it. -
Guide for GL devs describing how to document it.
Who can address the issue
@marcia (TW for development guidelines)
Other links/references
TBA