Feature flag rollout docs: clarify doc & checklist WRT removal steps

It wasn't clear from the existing checklist item added in
2d9d7f9c9 (Add roll out issue template, 2019-06-11) what the removal
steps are, and what "remove feature flag" meant.

Split this up into steps where we discuss the removal from the
codebase, and what changelog entries we expect there, and then discuss
how to remove the feature via chatops.

2 files changed, 36 insertions, 1 deletions

diff --git a/.gitlab/issue_templates/Feature Flag Roll Out.md b/.gitlab/issue_templates/Feature Flag Roll Out.md
index da2732616..58732b493 100644
--- a/.gitlab/issue_templates/Feature Flag Roll Out.md
+++ b/.gitlab/issue_templates/Feature Flag Roll Out.md
@@ -61,7 +61,9 @@ If applicable, any groups/projects that are happy to have this feature turned on
 - [ ] Submit a MR to have the feature `OnByDefault: true` and add changelog entry ([howto](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/PROCESS.md#feature-lifecycle-after-it-is-live))
 - [ ] Have that MR merged
 - [ ] Possibly wait for at least one deployment cycle ([howto](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/PROCESS.md#two-phase-ruby-to-go-rollouts))
-- [ ] Remove feature flag and add changelog entry
+- [ ] Submit an MR to remove the pre-feature code from the codebase and add changelog entry ([howto](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/PROCESS.md#feature-lifecycle-after-it-is-live))
+- [ ] Have that MR merged
+- [ ] Remove the feature flag via chatops ([howto](https://gitlab.com/gitlab-org/gitaly/-/blob/master/doc/PROCESS.md#remove-the-feature-flag-via-chatops))
 - [ ] Close this issue
 
 /label ~"devops::create" ~"group::gitaly" ~"feature flag" ~"feature::maintainance" ~"Category:Gitaly" ~"section::dev" ~"featureflag::disabled"
diff --git a/doc/PROCESS.md b/doc/PROCESS.md
index e8f8e6eb6..652bc73ff 100644
--- a/doc/PROCESS.md
+++ b/doc/PROCESS.md
@@ -222,6 +222,17 @@ After a feature is running at `100%` for what ever's deemed to be a
 safe amount of time we should change it to be `OnByDefault: true`. See
 [this MR for an example][example-on-by-default-mr].
 
+We should add a changelog entry when `OnByDefault: true` is flipped.
+
+That should then be followed up by another MR to remove the
+pre-feature code from the codebase, and we should add another
+changelog entry when doing that.
+
+This is because even after setting `OnByDefault: true` users might
+still have opted to disable the new feature. See [the discussion
+below](#two-phase-ruby-to-go-rollouts)) for possibly needing to do
+such changes over multiple releases.
+
 [example-on-by-default-mr]: https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3033
 
 ##### Two phase Ruby to Go rollouts
@@ -242,6 +253,28 @@ two-phase removal.
 [example-on-by-default-mr]: https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3033
 [example-post-go-ruby-code-removal-mr]: https://gitlab.com/gitlab-org/gitaly/-/merge_requests/3056
 
+##### Remove the feature flag via chatops
+
+After completing the above steps the feature flag should be deleted
+from the database of available features via `chatops`.
+
+If you don't do this others will continue to see the features with
+e.g.:
+
+	/chatops run feature list --match=gitaly_
+
+It also incrementally adds to data that needs to be fetched &
+populated on every request.
+
+To remove the flag first sanity check that it's the feature you want,
+that it's at [`100%` and is `true`](#enable-in-production):
+
+	/chatops run feature get gitaly_X
+
+Then delete it if that's the data you're expecting:
+
+	/chatops run feature delete gitaly_X
+
 ### Gitaly Releases
 
 Gitaly releases are tagged automatically by