Require a changelog entry for all [feature flag] changes
What
Whenever a feature flag is added, changed, or removed, customers want to know about the change.
As described in https://gitlab.zendesk.com/agent/tickets/184939 (internal access only), we have a customer who
- Was surprised by the removal of a feature flag
- Looked through the changelog, and so no related notification
- Asked us to create notifications to prevent such surprises in the future
Owners
- Team: NAME_OF_TEAM
- Most appropriate slack channel to reach out to:
#g_TEAM_NAME
- Best individual to reach out to: NAME
Expectations
Customers should be able to search our changelog for feature flag changes. Ideally, the feature flag changelog message will include:
- Change in feature flag (added, modified, removed)
- Feature flag topic
- Related MR (which would then include a link to relevant documentation)
To ensure that changelog entries are added for all feature flag changes, we should revise https://docs.gitlab.com/ee/development/changelog.html#what-warrants-a-changelog-entry to:
- Require a changelog entry for all feature flag changes
Since many feature flag changes are implemented later as "docs-only" changes, modify the "docs-only" bullet to include something like:
- "Docs-only changes that affect feature flags must have a changelog entry, unless one was created in a previous MR."
Typical changelog entries
Here's what I'd expect for changelog entries:
- implemented with a feature flag. Disabled by default. !some_MR
- feature flag updated. Now enabled by default. !some_other_MR
- feature flag removed. Enabled by default. !a_different_MR
Beta groups/projects
If applicable, any groups/projects that are happy to have this feature turned on early. Some organizations may wish to test big changes they are interested in with a small subset of users ahead of time for example.
-
gitlab-org/gitlab
project -
gitlab-org
/gitlab-com
groups - ...
/chatops run feature set --project=gitlab-org/gitlab feature_name false