Follow-up from "Moving feature flag process docs to handbook"
The following discussions from !76630 (merged) should be addressed:
-
@jheimbuck_gl started a discussion: 1. Removing the flag, cleaning up and feature announcement:
-
@jheimbuck_gl started a discussion: 1. If the originating issue will be included in the Release Post coordinate with PM, PMM and TW to include the Release Post Item
@rickywiens - minor addition to ensure we're capturing when to publish the release post item
-
@rickywiens started a discussion: (+1 comment) @jheimbuck_gl I agree with your changes, but I would like to try and ensure this MR is as close to a copy/paste as possible, then apply changes like these in the follow up MR (bullet 4 in the plan: gitlab-org/gitlab#249129 (comment 523228764)).
-
@marcia started a discussion: This page contains the process of the feature flag lifecycle for GitLab team members. Technical information for GitLab developers and code contributors can be found in the [developer documentation](https://docs.gitlab.com/ee/development/feature_flags/index.html).
-
@marcia started a discussion: 1. New features in high traffic areas (e.g., a new merge request widget, a new option in issues/epics, a new CI functionality).
-
@marcia started a discussion: 1. Complex performance improvements that may require additional testing in production (e.g., rewriting complex queries, changes to frequently used API endpoints).
-
@marcia started a discussion: 1. Invasive changes to the user interface (e.g., introducing a new navigation bar, removal of a sidebar, UI element change in issues or MR interface).
-
@marcia started a discussion: 1. Introducing dependencies on third-party services (e.g., adding support for importing projects).
-
@marcia started a discussion: 1. Changes to features that can cause data corruption or cause data loss (e.g., features that process repository data or user-uploaded content).
-
@marcia started a discussion: 1. Adding a new API endpoint.
-
@marcia started a discussion: 1. Introducing new features in low traffic areas (e.g., adding a new export functionality in the admin area/group settings/project settings).
Actually, this is a little ambiguous (whether we are referring to one of the listed items or if they all are part of one nav item). So, consider changing this to, either:
1. Introducing new features in low traffic areas (e.g., adding a new export functionality in the **Admin area > Group settings > Project settings**).
Or:
1. Introducing new features in low traffic areas (e.g., adding a new export functionality in the admin area, group settings, or project settings).
-
@marcia started a discussion: 1. Non-invasive frontend changes (e.g., changing the color of a button, or moving a UI element in a low traffic area).
We can consider changing to:
1. Non-invasive frontend changes (e.g., slightly changing the color of a button, or moving a UI element in a low traffic area).
Since our brain does process color patterns strongly. ;)
-
@marcia started a discussion: In all cases, if you're working on changes like these, ask yourself:
-
@marcia started a discussion: > Why do I need to add a feature flag? If I don't add one, what options do I have to control the impact on application reliability and user experience?
-
@marcia started a discussion: For perspective on why we limit our use of feature flags watch the video
-
@marcia started a discussion: In case you are uncertain whether a feature flag is necessary, ask about this early in your merge request review process, and reviewers will likely provide you with an answer.
-
@marcia started a discussion: follow the [training template](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab/issue_templates/feature-flag-training.md).
-
@marcia started a discussion: Before using feature flags, make sure to read the information on this page and the following development guides:
-
@marcia started a discussion: How to document features deployed behind feature flags according to their state, and how to update the
-
@marcia started a discussion: docs when their state change.
-
@marcia started a discussion: For information about how the user will interact with features behind flags, see:
-
@marcia started a discussion: 1. You, as an engineer, come up with a proposed solution to the issue you're working on and decide whether you'll implement it behind a feature flag.
-
@marcia started a discussion: 1. Decide how you will implement the feature flag and its rollout according to:
-
@marcia started a discussion: 1. Choose the feature flag [type](https://docs.gitlab.com/ee/development/feature_flags/development.html#types-of-feature-flags).
-
@marcia started a discussion: 1. [Include the feature flag in tests](https://docs.gitlab.com/ee/development/feature_flags/development.html#feature-flags-in-tests) to check its behavior when enabled and disabled.
-
@marcia started a discussion: Engs test the feature or the flag?
🤔 To clarify this, I suggest either:1. [Use the feature locally](https://docs.gitlab.com/ee/development/feature_flags/development.html#enabling-a-feature-flag-locally-in-development) to ensure it works.
Or:
1. [Flip the feature flag locally](https://docs.gitlab.com/ee/development/feature_flags/development.html#enabling-a-feature-flag-locally-in-development) to ensure it works.
-
@marcia started a discussion: 1. Add the feature behind the flag to the codebase through an MR following the [implementation process](#feature-flags-in-gitlab-development). .```
-
@marcia started a discussion: What next step? Documentation? If not, shouldn't we move this item to the end of the list, given that all features introduced to the codebase must be documented?
-
@marcia started a discussion: I think we haven't mentioned the rollout issue so far. Shouldn't we define it before this line?
Maybe reword to something like:
1. Create a [rollout issue](#rollout) describing the implementation plan until the feature flag removal. 1. Some teams may choose to close the feature issue at this moment, once it is complete. Other teams may want to wait until the feature flag rollout issue is closed. If you close your feature issues after the code is present in the default branch, you should close the feature issue here.
-
@marcia started a discussion: I think this is for after the decision was made, right? Like, as a dev, 1st I evaluate if I'll use an FF. If I decide to use it, then, this is how I should proceed. Does it make sense? If so, maybe change to:
When you opt to deploy a feature behind a flag:
-
@marcia started a discussion: the status of a feature behind the feature flag in the documentation and with responsible stakeholders. The
-
@marcia started a discussion: I think we can stop the list before this item and leave it for another paragraph:
When the feature implementation is delivered among multiple merge requests:
WDYT?
-
@marcia started a discussion: (**disabled by default**) in the first merge request of your implementation.
-
@marcia started a discussion: 1. Submit incremental changes ensuring that any
-
@marcia started a discussion: new code added can only be reached if the feature flag is **enabled**.
-
@marcia started a discussion: Feature flags do not need to stick around for an entire release and be removed only in the next release. The feature needs to remain behind a flag until it
-
@marcia started a discussion: This note seems a little lost here. We say "such action" but it's not clear what this action is.
🤔 Maybe we only need to move this note before the previous paragraph about documentation. If so:**Note:** consider that, by removing the flag, the feature will become available on GitLab.com shortly after the merge request was merged.
-
@marcia started a discussion: When reading about the process, you can think that deploying a feature behind a feature flag
-
@marcia started a discussion: adds a lot of work. Fortunately, this is not the case, and we'll show why. For
-
@marcia started a discussion: I think this section should be before the process:
- What to do.
- Why should I do it.
- How should I do it.
Does it make sense?
-
@marcia started a discussion: I think this should come after the benefits. ;)
-
@marcia started a discussion: (+5 comments) @rickywiens great MR, thanks for working on this!
I've left some suggestions, could you please take a look and assign me back when ready? Tnx!!
🙇 -
@shinya.maeda started a discussion: (+1 comment) If this MR is just to move the process.md and index.md to somewhere else, I don't have nothing to say. I'm looking forward to seeing how we reorganize the sections of docs for gitlab-org/gitlab#249129 (closed). It looks already messy and need some restructuring.