Add latest changes from gitlab-org/gitlab@master

2 files changed, 59 insertions, 22 deletions

diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md
index a5b47b3a5c0..4ac33fddfd2 100644
--- a/doc/development/documentation/index.md
+++ b/doc/development/documentation/index.md
@@ -374,17 +374,29 @@ The following GitLab features are used among others:
 
 ## Testing
 
-We treat documentation as code, and so use tests to maintain the standards and quality of the docs.
-The current tests are:
-
-1. `docs lint`: Check that all internal (relative) links work correctly and
-   that all cURL examples in API docs use the full switches. It's recommended
-   to [check locally](#previewing-the-changes-live) before pushing to GitLab by executing the command
-   `bundle exec nanoc check internal_links` on your local
-   [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory. In addition,
-   `docs-lint` also runs [`markdownlint`](#markdownlint) to ensure the
-   markdown is consistent across all documentation.
-1. In a full pipeline, tests for [`/help`](#gitlab-help-tests).
+We treat documentation as code, and so use tests in our CI pipeline to maintain the
+standards and quality of the docs. The current tests, which run in CI jobs when a
+merge request with new or changed docs is submitted, are:
+
+- [`docs lint`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L48):
+  Runs several tests on the content of the docs themselves:
+  - [`lint-doc.sh` script](https://gitlab.com/gitlab-org/gitlab/blob/master/scripts/lint-doc.sh)
+    checks that:
+    - All cURL examples use the long flags (ex: `--header`, not `-H`).
+    - The `CHANGELOG.md` does not contain duplicate versions.
+    - No files in `doc/` are executable.
+    - No new `README.md` was added.
+  - [`markdownlint`](#markdownlint).
+  - Nanoc tests, which you can [run locally](#previewing-the-changes-live) before
+    pushing to GitLab by executing the command `bundle exec nanoc check internal_links`
+    (or `internal_anchors`) on your local [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory:
+    - [`internal_links`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L67)
+      checks that all internal links (ex: `[link](../index.md)`) are valid.
+    - [`internal_anchors`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/docs.gitlab-ci.yml#L69)
+      checks that all internal anchors (ex: `[link](../index.md#internal_anchor)`)
+      are valid.
+- If any code or the `doc/README.md` file is changed, a full pipeline will run, which
+  runs tests for [`/help`](#gitlab-help-tests).
 
 ### Linting
 
@@ -490,7 +502,10 @@ four repos that are the sources for <https://docs.gitlab.com>:
 - <https://gitlab.com/charts/gitlab/blob/master/.markdownlint.json>
 
 By default all rules are enabled, so the configuration file is used to disable unwanted
-rules, and also to configure optional parameters for enabled rules as needed.
+rules, and also to configure optional parameters for enabled rules as needed. You can
+also check [the issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/64352) that
+tracked the changes required to implement these rules, and details which rules were
+on or off when `markdownlint` was enabled on the docs.
 
 ## Danger Bot
 
diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
index c8664831736..39f8f1bfea6 100644
--- a/doc/development/feature_flags/controls.md
+++ b/doc/development/feature_flags/controls.md
@@ -1,9 +1,11 @@
-# Access for enabling a feature flag in production
+# Feature flag controls
 
-In order to be able to turn on/off features behind feature flags in any of the
+## Access
+
+To be able to turn on/off features behind feature flags in any of the
 GitLab Inc. provided environments such as staging and production, you need to
-have access to the chatops bot. Chatops bot is currently running on the ops instance,
-which is different from <https://gitlab.com> or <https://dev.gitlab.org>.
+have access to the [Chatops](../chatops_on_gitlabcom.md) bot. The Chatops bot
+is currently running on the ops instance, which is different from <https://gitlab.com> or <https://dev.gitlab.org>.
 
 Follow the Chatops document to [request access](../chatops_on_gitlabcom.md#requesting-access).
 
@@ -14,6 +16,19 @@ run:
 /chatops run feature --help
 ```
 
+## Where to run commands
+
+To increase visibility, we recommend that GitLab team members run feature flag
+related Chatops commands within certain slack channels based on the environment
+and related feature. For the [staging](https://staging.gitlab.com)
+and [development](https://dev.gitlab.org) environments of GitLab.com,
+the commands should run in a channel for the stage the feature is relevant too.
+
+For example, use the `#s_monitor` channel for features developed by the
+Monitor stage, Health group.
+
+For all production environment Chatops commands, use the `#production` channel.
+
 ## Rolling out changes
 
 When the changes are deployed to the environments it is time to start
@@ -28,7 +43,7 @@ easier to measure the impact of both separately.
 GitLab's feature library (using
 [Flipper](https://github.com/jnunemaker/flipper), and covered in the [Feature
 Flags process](process.md) guide) supports rolling out changes to a percentage of
-users. This in turn can be controlled using [GitLab chatops](../../ci/chatops/README.md).
+users. This in turn can be controlled using [GitLab Chatops](../../ci/chatops/README.md).
 
 For an up to date list of feature flag commands please see [the source
 code](https://gitlab.com/gitlab-com/chatops/blob/master/lib/chatops/commands/feature.rb).
@@ -37,7 +52,7 @@ Note that all the examples in that file must be preceded by
 
 If you get an error "Whoops! This action is not allowed. This incident
 will be reported." that means your Slack account is not allowed to
-change feature flags or you do not [have access](#access-for-enabling-a-feature-flag-in-production).
+change feature flags or you do not [have access](#access).
 
 ### Enabling feature for internal testing
 
@@ -64,7 +79,7 @@ there for any exceptions while testing your feature after enabling the feature f
 Once you are confident enough that these environments are in a good state with your
 feature enabled, you can roll out the change to GitLab.com.
 
-## Enabling feature for GitLab.com
+### Enabling a feature for GitLab.com
 
 Similar to above, to enable a feature for 25% of all users, run the following in
 Slack:
@@ -114,10 +129,17 @@ merge request has to be picked into a stable branch, make sure to also add the
 appropriate "Pick into X" label (e.g. "Pick into XX.X").
 See [the process document](process.md#including-a-feature-behind-feature-flag-in-the-final-release) for further details.
 
-When a feature gate has been removed from the code base, the value still exists
-in the database.
-This can be removed through ChatOps:
+When a feature gate has been removed from the code base, the feature
+record still exists in the database that the flag was deployed too.
+The record can be deleted once the MR is deployed to each environment:
 
+```sh
+/chatops run feature delete some_feature --dev
+/chatops run feature delete some_feature --staging
 ```
+
+Then, you can delete it from production after the MR is deployed to prod:
+
+```sh
 /chatops run feature delete some_feature
 ```