Automatic merge of gitlab-org/gitlab master

app/assets/javascripts/behaviors/shortcuts/keybindings.js

@@ -29,6 +29,7 @@ export const customizations = parsedCustomizations;
 
 // All available commands
 export const TOGGLE_PERFORMANCE_BAR = 'globalShortcuts.togglePerformanceBar';
+export const TOGGLE_CANARY = 'globalShortcuts.toggleCanary';
 
 /** All keybindings, grouped and ordered with descriptions */
 export const keybindingGroups = [
@@ -42,6 +43,12 @@ export const keybindingGroups = [
         // eslint-disable-next-line @gitlab/require-i18n-strings
         defaultKeys: ['p b'],
       },
+      {
+        description: s__('KeyboardShortcuts|Toggle GitLab Next'),
+        command: TOGGLE_CANARY,
+        // eslint-disable-next-line @gitlab/require-i18n-strings
+        defaultKeys: ['g x'],
+      },
     ],
   },
 ]

app/assets/javascripts/behaviors/shortcuts/shortcuts.js

@@ -9,7 +9,7 @@ import axios from '../../lib/utils/axios_utils';
 import { refreshCurrentPage, visitUrl } from '../../lib/utils/url_utility';
 import findAndFollowLink from '../../lib/utils/navigation_utility';
 import { parseBoolean, getCspNonceValue } from '~/lib/utils/common_utils';
-import { keysFor, TOGGLE_PERFORMANCE_BAR } from './keybindings';
+import { keysFor, TOGGLE_PERFORMANCE_BAR, TOGGLE_CANARY } from './keybindings';
 
 const defaultStopCallback = Mousetrap.prototype.stopCallback;
 Mousetrap.prototype.stopCallback = function customStopCallback(e, element, combo) {
@@ -72,6 +72,7 @@ export default class Shortcuts {
     Mousetrap.bind('/', Shortcuts.focusSearch);
     Mousetrap.bind('f', this.focusFilter.bind(this));
     Mousetrap.bind(keysFor(TOGGLE_PERFORMANCE_BAR), Shortcuts.onTogglePerfBar);
+    Mousetrap.bind(keysFor(TOGGLE_CANARY), Shortcuts.onToggleCanary);
 
     const findFileURL = document.body.dataset.findFile;
 
@@ -124,6 +125,14 @@ export default class Shortcuts {
     refreshCurrentPage();
   }
 
+  static onToggleCanary(e) {
+    e.preventDefault();
+    const canaryCookieName = 'gitlab_canary';
+    const currentValue = parseBoolean(Cookies.get(canaryCookieName));
+    Cookies.set(canaryCookieName, (!currentValue).toString(), { expires: 365, path: '/' });
+    refreshCurrentPage();
+  }
+
   static toggleMarkdownPreview(e) {
     // Check if short-cut was triggered while in Write Mode
     const $target = $(e.target);

app/views/help/_shortcuts.html.haml

@@ -60,6 +60,12 @@
                     %kbd p
                     %kbd b
                   %td= _('Toggle the Performance Bar')
+                - if Gitlab.com?
+                  %tr
+                    %td.shortcut
+                      %kbd g
+                      %kbd x
+                    %td= _('Toggle GitLab Next')
               %tbody
                 %tr
                   %th

changelogs/unreleased/kassio-bulkimports-log-pipeline-step-on-failures.yml

+---
+title: 'BulkImports: Add pipeline step to the failures log'
+merge_request: 52345
+author:
+type: changed

changelogs/unreleased/yo-canary-shortcut.yml

+---
+title: Keyboard shortcut for switching to GitLab next (Canary)
+merge_request: 51834
+author: Yogi (@yo)
+type: added

db/migrate/20210122155158_add_pipeline_step_to_bulk_imports_failures.rb

+# frozen_string_literal: true
+
+class AddPipelineStepToBulkImportsFailures < ActiveRecord::Migration[6.0]
+  include Gitlab::Database::MigrationHelpers
+
+  DOWNTIME = false
+
+  disable_ddl_transaction!
+
+  def up
+    unless column_exists?(:bulk_import_failures, :pipeline_step, :text)
+      with_lock_retries do
+        add_column :bulk_import_failures, :pipeline_step, :text
+      end
+    end
+
+    add_text_limit :bulk_import_failures, :pipeline_step, 255
+  end
+
+  def down
+    with_lock_retries do
+      remove_column :bulk_import_failures, :pipeline_step
+    end
+  end
+end

db/schema_migrations/20210122155158

+5f326f101ff06993e9160b0486d24d615abd6d5027b375e422f776181ad8a193
\ No newline at end of file

db/structure.sql

@@ -10074,8 +10074,10 @@ CREATE TABLE bulk_import_failures (
     exception_class text NOT NULL,
     exception_message text NOT NULL,
     correlation_id_value text,
+    pipeline_step text,
     CONSTRAINT check_053d65c7a4 CHECK ((char_length(pipeline_class) <= 255)),
     CONSTRAINT check_6eca8f972e CHECK ((char_length(exception_message) <= 255)),
+    CONSTRAINT check_721a422375 CHECK ((char_length(pipeline_step) <= 255)),
     CONSTRAINT check_c7dba8398e CHECK ((char_length(exception_class) <= 255)),
     CONSTRAINT check_e787285882 CHECK ((char_length(correlation_id_value) <= 255))
 );

doc/.vale/gitlab/spelling-exceptions.txt

@@ -411,6 +411,7 @@ reauthenticate
 reauthenticated
 reauthenticates
 reauthenticating
+rebalancing
 rebar
 rebase
 rebased
@@ -482,6 +483,7 @@ serializer
 serializers
 serializing
 serverless
+sharded
 sharding
 shfmt
 Shibboleth

doc/administration/git_protocol.md

@@ -29,11 +29,11 @@ server to accept the `GIT_PROTOCOL` environment.
 
 In installations using [GitLab Helm Charts](https://docs.gitlab.com/charts/)
 and [All-in-one Docker image](https://docs.gitlab.com/omnibus/docker/), the SSH
-service is already configured to accept the `GIT_PROTOCOL` environment and users
+service is already configured to accept the `GIT_PROTOCOL` environment. Users
 need not do anything more.
 
-For Omnibus GitLab and installations from source, you have to manually update
-the SSH configuration of your server by adding the line below to the `/etc/ssh/sshd_config` file:
+For Omnibus GitLab and installations from source, update
+the SSH configuration of your server manually by adding this line to the `/etc/ssh/sshd_config` file:
 
 ```plaintext
 AcceptEnv GIT_PROTOCOL

doc/administration/gitaly/index.md

@@ -40,7 +40,7 @@ The following is a high-level architecture overview of how Gitaly is used.
 
 ## Configure Gitaly
 
-The Gitaly service itself is configured via a [TOML configuration file](reference.md).
+The Gitaly service itself is configured by using a [TOML configuration file](reference.md).
 
 To change Gitaly settings:
 
@@ -121,7 +121,7 @@ The following list depicts the network architecture of Gitaly:
   - GitLab Shell.
   - Elasticsearch indexer.
   - Gitaly itself.
-- A Gitaly server must be able to make RPC calls **to itself** via its own
+- A Gitaly server must be able to make RPC calls **to itself** by uing its own
   `(Gitaly address, Gitaly token)` pair as specified in `/config/gitlab.yml`.
 - Authentication is done through a static token which is shared among the Gitaly and GitLab Rails
   nodes.
@@ -502,8 +502,8 @@ If it's excluded, default Git storage directory is used for that storage shard.
 
 ### Disable Gitaly where not required (optional)
 
-If you are running Gitaly [as a remote service](#run-gitaly-on-its-own-server), you may want to
-disable the local Gitaly service that runs on your GitLab server by default and have it only running
+If you run Gitaly [as a remote service](#run-gitaly-on-its-own-server), consider
+disabling the local Gitaly service that runs on your GitLab server by default, and only run it
 where required.
 
 Disabling Gitaly on the GitLab instance only makes sense when you run GitLab in a custom cluster configuration, where
@@ -538,7 +538,7 @@ To disable Gitaly on a GitLab server:
 > - [Introduced](https://gitlab.com/gitlab-org/gitaly/-/issues/3160) in GitLab 13.6, outgoing TLS connections to GitLab provide client certificates if configured.
 
 Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure
-connections, you must use `tls://` URL scheme in the `gitaly_address` of the corresponding
+connections, use the `tls://` URL scheme in the `gitaly_address` of the corresponding
 storage entry in the GitLab configuration.
 
 Gitaly provides the same server certificates as client certificates in TLS
@@ -935,12 +935,13 @@ Note that `enforced="true"` means that authentication is being enforced.
 
 ## Direct Git access bypassing Gitaly
 
-While it is possible to access Gitaly repositories stored on disk directly with a Git client,
-it is not advisable because Gitaly is being continuously improved and changed. Theses improvements may invalidate assumptions, resulting in performance degradation, instability, and even data loss.
+GitLab doesn't advise directly accessing Gitaly repositories stored on disk with
+a Git client, because Gitaly is being continuously improved and changed. These
+improvements may invalidate assumptions, resulting in performance degradation, instability, and even data loss.
 
 Gitaly has optimizations, such as the
 [`info/refs` advertisement cache](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/design_diskcache.md),
-that rely on Gitaly controlling and monitoring access to repositories via the
+that rely on Gitaly controlling and monitoring access to repositories by using the
 official gRPC interface. Likewise, Praefect has optimizations, such as fault
 tolerance and distributed reads, that depend on the gRPC interface and
 database to determine repository state.
@@ -979,11 +980,11 @@ lookup. Even when Gitaly is able to re-use an already-running `git` process (for
 a commit), you still have:
 
 - The cost of a network roundtrip to Gitaly.
-- Within Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process.
+- Inside Gitaly, a write/read roundtrip on the Unix pipes that connect Gitaly to the `git` process.
 
 Using GitLab.com to measure, we reduced the number of Gitaly calls per request until the loss of
 Rugged's efficiency was no longer felt. It also helped that we run Gitaly itself directly on the Git
-file severs, rather than via NFS mounts. This gave us a speed boost that counteracted the negative
+file severs, rather than by using NFS mounts. This gave us a speed boost that counteracted the negative
 effect of not using Rugged anymore.
 
 Unfortunately, other deployments of GitLab could not remove NFS like we did on GitLab.com, and they
@@ -1018,7 +1019,7 @@ The result of these checks is cached.
 To see if GitLab can access the repository file system directly, we use the following heuristic:
 
 - Gitaly ensures that the file system has a metadata file in its root with a UUID in it.
-- Gitaly reports this UUID to GitLab via the `ServerInfo` RPC.
+- Gitaly reports this UUID to GitLab by using the `ServerInfo` RPC.
 - GitLab Rails tries to read the metadata file directly. If it exists, and if the UUID's match,
   assume we have direct access.
 
@@ -1085,7 +1086,7 @@ app nodes).
 ### Client side gRPC logs
 
 Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC
-client has its own log file which may contain useful information when
+client has its own log file which may contain debugging information when
 you are seeing Gitaly errors. You can control the log level of the
 gRPC client with the `GRPC_LOG_LEVEL` environment variable. The
 default level is `WARN`.
@@ -1100,7 +1101,7 @@ sudo GRPC_TRACE=all GRPC_VERBOSITY=DEBUG gitlab-rake gitlab:gitaly:check
 
 Sometimes you need to find out which Gitaly RPC created a particular Git process.
 
-One method for doing this is via `DEBUG` logging. However, this needs to be enabled
+One method for doing this is by using `DEBUG` logging. However, this needs to be enabled
 ahead of time and the logs produced are quite verbose.
 
 A lightweight method for doing this correlation is by inspecting the environment
@@ -1137,16 +1138,19 @@ sum(rate(grpc_client_handled_total[5m])) by (grpc_method) > 0
 
 ### Repository changes fail with a `401 Unauthorized` error
 
-If you're running Gitaly on its own server and notice that users can
-successfully clone and fetch repositories (via both SSH and HTTPS), but can't
-push to them or make changes to the repository in the web UI without getting a
-`401 Unauthorized` message, then it's possible Gitaly is failing to authenticate
-with the Gitaly client due to having the [wrong secrets file](#configure-gitaly-servers).
+If you run Gitaly on its own server and notice these conditions:
+
+- Users can successfully clone and fetch repositories by using both SSH and HTTPS.
+- Users can't push to repositories, or receive a `401 Unauthorized` message when attempting to
+  make changes to them in the web UI.
+
+Gitaly may be failing to authenticate with the Gitaly client because it has the
+[wrong secrets file](#configure-gitaly-servers).
 
 Confirm the following are all true:
 
 - When any user performs a `git push` to any repository on this Gitaly server, it
-  fails with the following error (note the `401 Unauthorized`):
+  fails with a `401 Unauthorized` error:
 
   ```shell
   remote: GitLab: 401 Unauthorized
@@ -1158,7 +1162,7 @@ Confirm the following are all true:
 - When any user adds or modifies a file from the repository using the GitLab
   UI, it immediately fails with a red `401 Unauthorized` banner.
 - Creating a new project and [initializing it with a README](../../gitlab-basics/create-project.md#blank-projects)
-  successfully creates the project but doesn't create the README.
+  successfully creates the project, but doesn't create the README.
 - When [tailing the logs](https://docs.gitlab.com/omnibus/settings/logs.html#tail-logs-in-a-console-on-the-server)
   on a Gitaly client and reproducing the error, you get `401` errors
   when reaching the `/api/v4/internal/allowed` endpoint:
@@ -1229,11 +1233,11 @@ update the secrets file on the Gitaly server to match the Gitaly client, then
 
 ### Command line tools cannot connect to Gitaly
 
-If you are having trouble connecting to a Gitaly server with command line (CLI) tools,
+If you can't connect to a Gitaly server with command line (CLI) tools,
 and certain actions result in a `14: Connect Failed` error message,
-it means that gRPC cannot reach your Gitaly server.
+gRPC cannot reach your Gitaly server.
 
-Verify that you can reach Gitaly via TCP:
+Verify you can reach Gitaly by using TCP:
 
 ```shell
 sudo gitlab-rake gitlab:tcp_check[GITALY_SERVER_IP,GITALY_LISTEN_PORT]

doc/administration/gitaly/praefect.md

@@ -105,7 +105,7 @@ sharding is:
   replicas.
 - Simpler management, because all Gitaly nodes are identical.
 
-Under some workloads, CPU and memory requirements may require a large fleet of Gitaly nodes and it
+Under some workloads, CPU and memory requirements may require a large fleet of Gitaly nodes. It
 can be uneconomical to have one to one replication factor.
 
 A hybrid approach can be used in these instances, where each shard is configured as a smaller
@@ -168,7 +168,7 @@ If you are using Google Cloud Platform, SoftLayer, or any other vendor that prov
 
 The communication between components is secured with different secrets, which
 are described below. Before you begin, generate a unique secret for each, and
-make note of it. This makes it easy to replace these placeholder tokens
+make note of it. This enables you to replace these placeholder tokens
 with secure tokens as you complete the setup process.
 
 1. `GITLAB_SHELL_SECRET_TOKEN`: this is used by Git hooks to make callback HTTP
@@ -260,13 +260,12 @@ this, set the corresponding IP or host address of the PgBouncer instance in
 - `praefect['database_port']`, for the port.
 
 Because PgBouncer manages resources more efficiently, Praefect still requires a
-direct connection to the PostgreSQL database because it uses
+direct connection to the PostgreSQL database. It uses the
 [LISTEN](https://www.postgresql.org/docs/11/sql-listen.html)
-functionality that is [not supported](https://www.pgbouncer.org/features.html) by
+feature that is [not supported](https://www.pgbouncer.org/features.html) by
 PgBouncer with `pool_mode = transaction`.
-
-Therefore, `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']`
-should be set to a direct connection and not a PgBouncer connection.
+Set `praefect['database_host_no_proxy']` and `praefect['database_port_no_proxy']`
+to a direct connection, and not a PgBouncer connection.
 
 Save the changes to `/etc/gitlab/gitlab.rb` and
 [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure).
@@ -960,14 +959,14 @@ To get started quickly:
    gitlab-ctl reconfigure
    ```
 
-1. Set the Grafana admin password. This command prompts you to enter a new
+1. Set the Grafana administrator password. This command prompts you to enter a new
    password:
 
    ```shell
    gitlab-ctl set-grafana-password
    ```
 
-1. In your web browser, open `/-/grafana` (e.g.
+1. In your web browser, open `/-/grafana` (such as
    `https://gitlab.example.com/-/grafana`) on your GitLab server.
 
    Login using the password you set, and the username `admin`.
@@ -1085,7 +1084,7 @@ specific storage nodes to host a repository.
 support configuring a default replication factor for a virtual storage. The default replication factor
 is applied to every newly-created repository.
 
-Prafect does not store the actual replication factor, but assigns enough storages to host the repository
+Praefect does not store the actual replication factor, but assigns enough storages to host the repository
 so the desired replication factor is met. If a storage node is later removed from the virtual storage,
 the replication factor of repositories assigned to the storage is decreased accordingly.
 
@@ -1164,8 +1163,8 @@ To enable writes again, an administrator can:
 
 ### Check for data loss
 
-The Praefect `dataloss` sub-command identifies replicas that are likely to be outdated. This is
-useful for identifying potential data loss after a failover. The following parameters are
+The Praefect `dataloss` sub-command identifies replicas that are likely to be outdated. This can help
+identify potential data loss after a failover. The following parameters are
 available:
 
 - `-virtual-storage` that specifies which virtual storage to check. The default behavior is to
@@ -1189,7 +1188,7 @@ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.t
 ```
 
 Repositories which have assigned storage nodes that contain an outdated copy of the repository are listed
-in the output. A number of useful information is printed for each repository:
+in the output. This information is printed for each repository:
 
 - A repository's relative path to the storage directory identifies each repository and groups the related
   information.
@@ -1206,7 +1205,7 @@ in the output. A number of useful information is printed for each repository:
 
 Whether a replica is assigned to host the repository is listed with each replica's status. `assigned host` is printed
 next to replicas which are assigned to store the repository. The text is omitted if the replica contains a copy of
-the repository but is not assigned to store the repository. Such replicas won't be kept in-sync by Praefect but may
+the repository but is not assigned to store the repository. Such replicas aren't kept in-sync by Praefect, but may
 act as replication sources to bring assigned replicas up to date.
 
 Example output:
@@ -1275,7 +1274,7 @@ To check a project's repository checksums across on all Gitaly nodes, run the
 
 ### Enable writes or accept data loss
 
-Praefect provides the following subcommands to re-enable writes:
+Praefect provides the following sub-commands to re-enable writes:
 
 - In GitLab 13.2 and earlier, `enable-writes` to re-enable virtual storage for writes after data
   recovery attempts.
@@ -1317,7 +1316,7 @@ These tools reconcile the outdated repositories to bring them fully up to date a
 
 Praefect automatically reconciles repositories that are not up to date. By default, this is done every
 five minutes. For each outdated repository on a healthy Gitaly node, the Praefect picks a
-random, fully up to date replica of the repository on another healthy Gitaly node to replicate from. A
+random, fully up-to-date replica of the repository on another healthy Gitaly node to replicate from. A
 replication job is scheduled only if there are no other replication jobs pending for the target
 repository.
 
@@ -1376,7 +1375,7 @@ To move repositories to Gitaly Cluster:
    - The moves are in progress. Re-query the repository move until it completes successfully.
    - The moves have failed. Most failures are temporary and are solved by rescheduling the move.
 
-1. Once the moves are complete, [query projects](../../api/projects.md#list-all-projects)
+1. After the moves are complete, [query projects](../../api/projects.md#list-all-projects)
    using the API to confirm that all projects have moved. No projects should be returned
    with `repository_storage` field set to the old storage.
 

doc/administration/gitaly/reference.md

@@ -95,13 +95,13 @@ key_path = '/home/git/key.pem'
 
 ### Storage
 
-GitLab repositories are grouped into directories known as "storages"
-(e.g., `/home/git/repositories`) containing bare repositories managed
-by GitLab with names (e.g., `default`).
+GitLab repositories are grouped into directories known as storages, such as
+`/home/git/repositories`. They contain bare repositories managed
+by GitLab with names, such as `default`.
 
 These names and paths are also defined in the `gitlab.yml` configuration file of
-GitLab. When you run Gitaly on the same machine as GitLab, which is the default
-and recommended configuration, storage paths defined in Gitaly's `config.toml`
+GitLab. When you run Gitaly on the same machine as GitLab (the default
+and recommended configuration) storage paths defined in Gitaly's `config.toml`
 must match those in `gitlab.yml`.
 
 | Name | Type | Required | Description |
@@ -232,9 +232,9 @@ The following values configure logging in Gitaly under the `[logging]` section.
 | ---- | ---- | -------- | ----------- |
 | `format` | string | no | Log format: `text` or `json`. Default: `text`. |
 | `level`  | string | no | Log level: `debug`, `info`, `warn`, `error`, `fatal`, or `panic`. Default: `info`. |
-| `sentry_dsn` | string | no | Sentry DSN for exception monitoring. |
+| `sentry_dsn` | string | no | Sentry DSN (Data Source Name) for exception monitoring. |
 | `sentry_environment` | string | no | [Sentry Environment](https://docs.sentry.io/product/sentry-basics/environments/) for exception monitoring. |
-| `ruby_sentry_dsn` | string | no | Sentry DSN for `gitaly-ruby` exception monitoring. |
+| `ruby_sentry_dsn` | string | no | Sentry DSN (Data Source Name) for `gitaly-ruby` exception monitoring. |
 
 While the main Gitaly application logs go to `stdout`, there are some extra log
 files that go to a configured directory, like the GitLab Shell logs.

doc/administration/integration/plantuml.md

@@ -10,13 +10,13 @@ type: reference, howto
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8537) in GitLab 8.16.
 
 When [PlantUML](https://plantuml.com) integration is enabled and configured in
-GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents
+GitLab you can create diagrams in AsciiDoc and Markdown documents
 created in snippets, wikis, and repositories.
 
 ## PlantUML Server
 
-Before you can enable PlantUML in GitLab; you need to set up your own PlantUML
-server that will generate the diagrams.
+Before you can enable PlantUML in GitLab; set up your own PlantUML
+server to generate the diagrams.
 
 ### Docker
 
@@ -26,12 +26,11 @@ With Docker, you can just run a container like this:
 docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:tomcat
 ```
 
-The **PlantUML URL** will be the hostname of the server running the container.
+The **PlantUML URL** is the hostname of the server running the container.
 
-When running GitLab in Docker, it will need to have access to the PlantUML container.
-The easiest way to achieve that is by using [Docker Compose](https://docs.docker.com/compose/).
-
-A simple `docker-compose.yml` file would be:
+When running GitLab in Docker, it must have access to the PlantUML container.
+You can achieve that by using [Docker Compose](https://docs.docker.com/compose/).
+A basic `docker-compose.yml` file could contain:
 
 ```yaml
 version: "3"
@@ -47,13 +46,12 @@ services:
     container_name: plantuml
 ```
 
-In this scenario, PlantUML will be accessible for GitLab at the URL
+In this scenario, PlantUML is accessible to GitLab at the URL
 `http://plantuml:8080/`.
 
 ### Debian/Ubuntu
 
-Installing and configuring your
-own PlantUML server is easy in Debian/Ubuntu distributions using Tomcat.
+You can also install and configure a PlantUML server in Debian/Ubuntu distributions using Tomcat.
 
 First you need to create a `plantuml.war` file from the source code:
 
@@ -64,8 +62,7 @@ cd plantuml-server
 mvn package
 ```
 
-The above sequence of commands will generate a WAR file that can be deployed
-using Tomcat:
+The above sequence of commands generates a `.war` file you can deploy with Tomcat:
 
 ```shell
 sudo apt-get install tomcat8
@@ -74,17 +71,18 @@ sudo chown tomcat8:tomcat8 /var/lib/tomcat8/webapps/plantuml.war
 sudo service tomcat8 restart
 ```
 
-Once the Tomcat service restarts the PlantUML service will be ready and
+After the Tomcat service restarts, the PlantUML service is ready and
 listening for requests on port 8080:
 
 ```plaintext
 http://localhost:8080/plantuml
 ```
 
-you can change these defaults by editing the `/etc/tomcat8/server.xml` file.
+To change these defaults, edit the `/etc/tomcat8/server.xml` file.
 
-Note that the default URL is different than when using the Docker-based image,
-where the service is available at the root of URL with no relative path. Adjust
+NOTE:
+The default URL is different when using this approach. The Docker-based image
+makes the service available at the root URL, with no relative path. Adjust
 the configuration below accordingly.
 
 ### Making local PlantUML accessible using custom GitLab setup
@@ -112,7 +110,7 @@ To activate the changes, run the following command:
 sudo gitlab-ctl reconfigure
 ```
 
-Note that the redirection through GitLab **must** be configured
+Note that the redirection through GitLab must be configured
 when running [GitLab with TLS](https://docs.gitlab.com/omnibus/settings/ssl.html)
 due to PlantUML's use of the insecure HTTP protocol. Newer browsers such
 as [Google Chrome 86+](https://www.chromestatus.com/feature/4926989725073408)
@@ -120,7 +118,7 @@ do not load insecure HTTP resources on a page served over HTTPS.
 
 ### Security
 
-PlantUML has features that allows fetching network resources.
+PlantUML has features that allow fetching network resources.
 
 ```plaintext
 @startuml
@@ -136,18 +134,18 @@ stop;
 ## GitLab
 
 You need to enable PlantUML integration from Settings under Admin Area. To do
-that, login with an Admin account and do following:
+that, sign in with an Administrator account, and then do following:
 
-- In GitLab, go to **Admin Area > Settings > General**.
-- Expand the **PlantUML** section.
-- Check **Enable PlantUML** checkbox.
-- Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`.
+1. In GitLab, go to **Admin Area > Settings > General**.
+1. Expand the **PlantUML** section.
+1. Select the **Enable PlantUML** check box.
+1. Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`.
 
 NOTE:
 If you are using a PlantUML server running v1.2020.9 and
 above (for example, [plantuml.com](https://plantuml.com)), set the `PLANTUML_ENCODING`
-environment variable to enable the `deflate` compression. On Omnibus,
-this can be done set in `/etc/gitlab.rb`:
+environment variable to enable the `deflate` compression. On Omnibus GitLab,
+this can be set in `/etc/gitlab.rb`:
 
 ```ruby
 gitlab_rails['env'] = { 'PLANTUML_ENCODING' => 'deflate' }
@@ -191,9 +189,11 @@ our AsciiDoc snippets, wikis, and repositories using delimited blocks:
      Alice -> Bob: hi
   ```
 
-   You can also use the `uml::` directive for compatibility with [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/), but please note that we currently only support the `caption` option.
+   You can also use the `uml::` directive for compatibility with
+   [`sphinxcontrib-plantuml`](https://pypi.org/project/sphinxcontrib-plantuml/),
+   but GitLab only supports the `caption` option.
 
-The above blocks will be converted to an HTML image tag with source pointing to the
+The above blocks are converted to an HTML image tag with source pointing to the
 PlantUML instance. If the PlantUML server is correctly configured, this should
 render a nice diagram instead of the block:
 
@@ -202,12 +202,18 @@ Bob -> Alice : hello
 Alice -> Bob : hi
 ```
 
-Inside the block you can add any of the supported diagrams by PlantUML such as
-[Sequence](https://plantuml.com/sequence-diagram), [Use Case](https://plantuml.com/use-case-diagram),
-[Class](https://plantuml.com/class-diagram), [Activity](https://plantuml.com/activity-diagram-legacy),
-[Component](https://plantuml.com/component-diagram), [State](https://plantuml.com/state-diagram),
-and [Object](https://plantuml.com/object-diagram) diagrams. You do not need to use the PlantUML
-diagram delimiters `@startuml`/`@enduml` as these are replaced by the AsciiDoc `plantuml` block.
+Inside the block you can add any of the diagrams PlantUML supports, such as:
+
+- [Sequence](https://plantuml.com/sequence-diagram)
+- [Use Case](https://plantuml.com/use-case-diagram)
+- [Class](https://plantuml.com/class-diagram)
+- [Activity](https://plantuml.com/activity-diagram-legacy)
+- [Component](https://plantuml.com/component-diagram)
+- [State](https://plantuml.com/state-diagram),
+- [Object](https://plantuml.com/object-diagram)
+
+You do not need to use the PlantUML
+diagram delimiters `@startuml`/`@enduml`, as these are replaced by the AsciiDoc `plantuml` block.
 
 Some parameters can be added to the AsciiDoc block definition:
 
@@ -217,4 +223,4 @@ Some parameters can be added to the AsciiDoc block definition:
 - `width`: Width attribute added to the image tag.
 - `height`: Height attribute added to the image tag.
 
-Markdown does not support any parameters and will always use PNG format.
+Markdown does not support any parameters and always uses PNG format.

doc/administration/integration/terminal.md

@@ -8,14 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7690) in GitLab 8.15.
 
-NOTE:
-Only project maintainers and owners can access web terminals.
-
 With the introduction of the [Kubernetes integration](../../user/project/clusters/index.md),
-GitLab gained the ability to store and use credentials for a Kubernetes cluster.
-One of the things it uses these credentials for is providing access to
+GitLab can store and use credentials for a Kubernetes cluster.
+GitLab uses these credentials to provide access to
 [web terminals](../../ci/environments/index.md#web-terminals) for environments.
 
+NOTE:
+Only project maintainers and owners can access web terminals.
+
 ## How it works
 
 A detailed overview of the architecture of web terminals and how they work
@@ -53,15 +53,13 @@ detail below.
 
 NOTE:
 AWS Elastic Load Balancers (ELBs) do not support web sockets.
-AWS Application Load Balancers (ALBs) must be used if you want web terminals
-to work. See [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare)
+If you want web terminals to work, use AWS Application Load Balancers (ALBs).
+Read [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare)
 for more information.
 
 As web terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of
-Workhorse needs to be configured to pass the `Connection` and `Upgrade` headers
-through to the next one in the chain. If you installed GitLab using Omnibus, or
-from source, starting with GitLab 8.15, this should be done by the default
-configuration, so there's no need for you to do anything.
+Workhorse must be configured to pass the `Connection` and `Upgrade` headers
+to the next one in the chain. GitLab is configured by default to do so.
 
 However, if you run a [load balancer](../load_balancer.md) in
 front of GitLab, you may need to make some changes to your configuration. These
@@ -73,17 +71,17 @@ guides document the necessary steps for a selection of popular reverse proxies:
 - [Varnish](https://varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html)
 
 Workhorse doesn't let WebSocket requests through to non-WebSocket endpoints, so
-it's safe to enable support for these headers globally. If you'd rather had a
-narrower set of rules, you can restrict it to URLs ending with `/terminal.ws`
-(although this may still have a few false positives).
+it's safe to enable support for these headers globally. If you prefer a
+narrower set of rules, you can restrict it to URLs ending with `/terminal.ws`.
+This approach may still result in a few false positives.
 
 If you installed from source, or have made any configuration changes to your
 Omnibus installation before upgrading to 8.15, you may need to make some changes
-to your configuration. See the [Upgrading Community Edition and Enterprise
-Edition from source](../../update/upgrading_from_source.md#nginx-configuration)
-document for more details.
+to your configuration. Read
+[Upgrading Community Edition and Enterprise Edition from source](../../update/upgrading_from_source.md#nginx-configuration)
+for more details.
 
-If you'd like to disable web terminal support in GitLab, just stop passing
+To disable web terminal support in GitLab, stop passing
 the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse
 proxy in the chain. For most users, this is the NGINX server bundled with
 Omnibus GitLab, in which case, you need to:
@@ -104,4 +102,6 @@ they receive a `Connection failed` message.
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/8413) in GitLab 8.17.
 
 Terminal sessions, by default, do not expire.
-You can limit terminal session lifetime in your GitLab instance. To do so, navigate to [**Admin Area > Settings > Web terminal**](../../user/admin_area/settings/index.md#general), and set a `max session time`.
+You can limit terminal session lifetime in your GitLab instance. To do so,
+go to [**Admin Area > Settings > Web terminal**](../../user/admin_area/settings/index.md#general),
+and set a `max session time`.

doc/administration/invalidate_markdown_cache.md

@@ -8,10 +8,10 @@ type: reference
 # Invalidate Markdown Cache
 
 For performance reasons, GitLab caches the HTML version of Markdown text
-(e.g. issue and merge request descriptions, comments). It's possible
-that these cached versions become outdated, for example
-when the `external_url` configuration option is changed - causing links
-in the cached text to refer to the old URL.
+in fields like comments, issue descriptions, and merge request descriptions. These
+cached versions can become outdated, such as
+when the `external_url` configuration option is changed. Links
+in the cached text would still refer to the old URL.
 
 To avoid this problem, the administrator can invalidate the existing cache by
 increasing the `local_markdown_version` setting in application settings. This can

doc/administration/merge_request_diffs.md

@@ -31,8 +31,8 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d
    gitlab_rails['external_diffs_enabled'] = true
    ```
 
-1. _The external diffs will be stored in
-   `/var/opt/gitlab/gitlab-rails/shared/external-diffs`._ To change the path,
+1. The external diffs are stored in
+   `/var/opt/gitlab/gitlab-rails/shared/external-diffs`. To change the path,
    for example, to `/mnt/storage/external-diffs`, edit `/etc/gitlab/gitlab.rb`
    and add the following line:
 
@@ -52,8 +52,8 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d
      enabled: true
    ```
 
-1. _The external diffs will be stored in
-   `/home/git/gitlab/shared/external-diffs`._ To change the path, for example,
+1. The external diffs are stored in
+   `/home/git/gitlab/shared/external-diffs`. To change the path, for example,
    to `/mnt/storage/external-diffs`, edit `/home/git/gitlab/config/gitlab.yml`
    and add or amend the following lines:
 
@@ -68,7 +68,7 @@ that only [stores outdated diffs](#alternative-in-database-storage) outside of d
 ## Using object storage
 
 WARNING:
-Currently migrating to object storage is **non-reversible**
+Migrating to object storage is not reversible.
 
 Instead of storing the external diffs on disk, we recommended the use of an object
 store like AWS S3 instead. This configuration relies on valid AWS credentials to
@@ -114,7 +114,7 @@ then `object_store:`. On Omnibus installations, they are prefixed by
 | Setting | Description | Default |
 |---------|-------------|---------|
 | `enabled` | Enable/disable object storage | `false` |
-| `remote_directory` | The bucket name where external diffs will be stored| |
+| `remote_directory` | The bucket name where external diffs are stored| |
 | `direct_upload` | Set to `true` to enable direct upload of external diffs without the need of local shared storage. Option may be removed once we decide to support only single storage for all files. | `false` |
 | `background_upload` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 | `true` |
 | `proxy_download` | Set to `true` to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` |
@@ -141,7 +141,7 @@ See [the available connection settings for different providers](object_storage.m
    }
    ```
 
-   Note that, if you are using AWS IAM profiles, be sure to omit the
+   If you are using AWS IAM profiles, omit the
    AWS access key and secret access key/value pairs. For example:
 
    ```ruby
@@ -206,8 +206,8 @@ To enable this feature, perform the following steps:
 
 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
-With this feature enabled, diffs will initially stored in the database, rather
-than externally. They will be moved to external storage once any of these
+With this feature enabled, diffs are initially stored in the database, rather
+than externally. They are moved to external storage after any of these
 conditions become true:
 
 - A newer version of the merge request diff exists
@@ -233,7 +233,7 @@ and the exception for that error is of this form:
 Errno::ENOENT (No such file or directory @ rb_sysopen - /var/opt/gitlab/gitlab-rails/shared/external-diffs/merge_request_diffs/mr-6167082/diff-8199789)
 ```
 
-Then you are affected by this issue. Since it's not possible to safely determine
+Then you are affected by this issue. Because it's not possible to safely determine
 all these conditions automatically, we've provided a Rake task in GitLab v13.2.0
 that you can run manually to correct the data:
 

doc/administration/operations/moving_repositories.md

@@ -20,8 +20,8 @@ The GitLab API is the recommended way to move Git repositories:
 
 For more information, see:
 
-- [Configuring additional storage for Gitaly](../gitaly/index.md#network-architecture). Within this
-  example, additional storage called `storage1` and `storage2` is configured.
+- [Configuring additional storage for Gitaly](../gitaly/index.md#network-architecture). This
+  example configures additional storage called `storage1` and `storage2`.
 - [The API documentation](../../api/project_repository_storage_moves.md) details the endpoints for
   querying and scheduling project repository moves.
 - [The API documentation](../../api/snippet_repository_storage_moves.md) details the endpoints for
@@ -38,7 +38,7 @@ Read more in the [API documentation for projects](../../api/project_repository_s
 GitLab environment, for example:
 
 - From a single-node GitLab to a scaled-out architecture.
-- From a GitLab instance in your private datacenter to a cloud provider.
+- From a GitLab instance in your private data center to a cloud provider.
 
 The rest of the document looks
 at some of the ways you can copy all your repositories from
@@ -103,8 +103,8 @@ Using `rsync` to migrate Git data can cause data loss and repository corruption.
 If the target directory already contains a partial / outdated copy
 of the repositories it may be wasteful to copy all the data again
 with `tar`. In this scenario it is better to use `rsync`. This utility
-is either already installed on your system or easily installable
-via `apt`, `yum`, and so on.
+is either already installed on your system, or installable
+by using `apt` or `yum`.
 
 ```shell
 sudo -u git  sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \
@@ -112,7 +112,7 @@ sudo -u git  sh -c 'rsync -a --delete /var/opt/gitlab/git-data/repositories/. \
 ```
 
 The `/.` in the command above is very important, without it you can
-easily get the wrong directory structure in the target directory.
+get the wrong directory structure in the target directory.
 If you want to see progress, replace `-a` with `-av`.
 
 #### Single `rsync` to another server
@@ -135,20 +135,23 @@ WARNING:
 Using `rsync` to migrate Git data can cause data loss and repository corruption.
 [These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422).
 
-Every time you start an `rsync` job it has to inspect all files in
-the source directory, all files in the target directory, and then
-decide what files to copy or not. If the source or target directory
-has many contents this startup phase of `rsync` can become a burden
-for your GitLab server. In cases like this you can make `rsync`'s
-life easier by dividing its work in smaller pieces, and sync one
-repository at a time.
+Every time you start an `rsync` job it must:
+
+- Inspect all files in the source directory.
+- Inspect all files in the target directory.
+- Decide whether or not to copy files.
+
+If the source or target directory
+has many contents, this startup phase of `rsync` can become a burden
+for your GitLab server. You can reduce the workload of `rsync` by dividing its
+work in smaller pieces, and sync one repository at a time.
 
 In addition to `rsync` we use [GNU Parallel](http://www.gnu.org/software/parallel/).
-This utility is not included in GitLab so you need to install it yourself with `apt`
-or `yum`. Also note that the GitLab scripts we used below were added in GitLab 8.1.
+This utility is not included in GitLab, so you must install it yourself with `apt`
+or `yum`.
 
-**This process does not clean up repositories at the target location that no
-longer exist at the source.**
+This process does not clean up repositories at the target location that no
+longer exist at the source.
 
 #### Parallel `rsync` for all repositories known to GitLab
 
@@ -218,8 +221,8 @@ Using `rsync` to migrate Git data can cause data loss and repository corruption.
 [These instructions are being reviewed](https://gitlab.com/gitlab-org/gitlab/-/issues/270422).
 
 Suppose you have already done one sync that started after 2015-10-1 12:00 UTC.
-Then you might only want to sync repositories that were changed via GitLab
-_after_ that time. You can use the `SINCE` variable to tell `rake
+Then you might only want to sync repositories that were changed by using GitLab
+after that time. You can use the `SINCE` variable to tell `rake
 gitlab:list_repos` to only print repositories with recent activity.
 
 ```shell

doc/administration/repository_checks.md

@@ -14,25 +14,24 @@ integrity of all data committed to a repository. GitLab administrators
 can trigger such a check for a project via the project page under the
 admin panel. The checks run asynchronously so it may take a few minutes
 before the check result is visible on the project admin page. If the
-checks failed you can see their output on in the [`repocheck.log`
-file.](logs.md#repochecklog)
+checks failed you can see their output on in the
+[`repocheck.log` file.](logs.md#repochecklog)
 
-NOTE:
-It is OFF by default because it still causes too many false alarms.
+This setting is off by default, because it can cause many false alarms.
 
 ## Periodic checks
 
 When enabled, GitLab periodically runs a repository check on all project
 repositories and wiki repositories in order to detect data corruption.
-A project will be checked no more than once per month. If any projects
-fail their repository checks all GitLab administrators will receive an email
+A project is checked no more than once per month. If any projects
+fail their repository checks all GitLab administrators receive an email
 notification of the situation. This notification is sent out once a week,
 by default, midnight at the start of Sunday. Repositories with known check
 failures can be found at `/admin/projects?last_repository_check_failed=1`.
 
 ## Disabling periodic checks
 
-You can disable the periodic checks on the 'Settings' page of the admin
+You can disable the periodic checks on the **Settings** page of the admin
 panel.
 
 ## What to do if a check failed
@@ -40,9 +39,9 @@ panel.
 If the repository check fails for some repository you should look up the error
 in the [`repocheck.log` file](logs.md#repochecklog) on disk:
 
-- `/var/log/gitlab/gitlab-rails` for Omnibus installations
+- `/var/log/gitlab/gitlab-rails` for Omnibus GitLab installations
 - `/home/git/gitlab/log` for installations from source
 
 If the periodic repository check causes false alarms, you can clear all repository check states by
-navigating to **Admin Area > Settings > Repository**
+going to **Admin Area > Settings > Repository**
 (`/admin/application_settings/repository`) and clicking **Clear all repository checks**.

doc/administration/repository_storage_paths.md

@@ -40,9 +40,9 @@ storage2:
 
 ## Configure GitLab
 
-In order for [backups](../raketasks/backup_restore.md) to work correctly, the storage path must **not** be a
-mount point and the GitLab user should have correct permissions for the parent
-directory of the path. In Omnibus GitLab this is taken care of automatically,
+For [backups](../raketasks/backup_restore.md) to work correctly, the storage path cannot be a
+mount point, and the GitLab user must have correct permissions for the parent
+directory of the path. Omnibus GitLab takes care of these issues for you,
 but for source installations you should be extra careful.
 
 The thing is that for compatibility reasons `gitlab.yml` has a different
@@ -52,22 +52,26 @@ indicate `git_data_dirs`, which for the example above would be `/home/git`.
 Then, Omnibus creates a `repositories` directory under that path to use with
 `gitlab.yml`.
 
-This little detail matters because while restoring a backup, the current
-contents of `/home/git/repositories` [are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) `/home/git/repositories.old`,
-so if `/home/git/repositories` is the mount point, then `mv` would be moving
+WARNING:
+This detail matters because while restoring a backup, the current
+contents of `/home/git/repositories`
+[are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56)
+`/home/git/repositories.old`.
+If `/home/git/repositories` is the mount point, then `mv` would be moving
 things between mount points, and bad things could happen. Ideally,
-`/home/git` would be the mount point, so then things would be moving within the
-same mount point. This is guaranteed with Omnibus installations (because they
-don't specify the full repository path but the parent path), but not for source
-installations.
+`/home/git` would be the mount point, so things would remain inside the
+same mount point. Omnibus installations guarantee this, because they
+don't specify the full repository path but instead the parent path, but source
+installations do not.
 
-Now that you've read that big fat warning above, let's edit the configuration
-files and add the full paths of the alternative repository storage paths. In
+Next, edit the configuration
+files, and add the full paths of the alternative repository storage paths. In
 the example below, we add two more mount points that are named `nfs_1` and `nfs_2`
 respectively.
 
 NOTE:
-This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. See the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details.
+This example uses NFS. We do not recommend using EFS for storage as it may impact GitLab performance. Read
+the [relevant documentation](nfs.md#avoid-using-awss-elastic-file-system-efs) for more details.
 
 **For installations from source**
 
@@ -112,7 +116,7 @@ working, you can remove the `repos_path` line.
 
 ## Choose where new repositories are stored
 
-Once you set the multiple storage paths, you can choose where new repositories
+After you set the multiple storage paths, you can choose where new repositories
 are stored in the Admin Area under **Settings > Repository > Repository storage > Storage nodes for new repositories**.
 
 Each storage can be assigned a weight from 0-100. When a new project is created, these

doc/administration/repository_storage_types.md

@@ -38,13 +38,13 @@ been disabled.
 
 Hashed storage is the storage behavior we rolled out with 10.0. Instead
 of coupling project URL and the folder structure where the repository is
-stored on disk, we are coupling a hash, based on the project's ID. This makes
+stored on disk, we couple a hash based on the project's ID. This makes
 the folder structure immutable, and therefore eliminates any requirement to
 synchronize state from URLs to disk structure. This means that renaming a group,
 user, or project costs only the database transaction, and takes effect
 immediately.
 
-The hash also helps to spread the repositories more evenly on the disk, so the
+The hash also helps spread the repositories more evenly on the disk. The
 top-level directory contains fewer folders than the total number of top-level
 namespaces.
 
@@ -136,8 +136,8 @@ when housekeeping is run on the source project.
 ### Hashed storage coverage migration
 
 Files stored in an S3-compatible endpoint do not have the downsides
-mentioned earlier, if they are not prefixed with `#{namespace}/#{project_name}`,
-which is true for CI Cache and LFS Objects.
+mentioned earlier, if they are not prefixed with `#{namespace}/#{project_name}`.
+This is true for CI Cache and LFS Objects.
 
 In the table below, you can find the coverage of the migration to the hashed storage.
 
@@ -194,10 +194,10 @@ reasons, GitLab replicated the same mapping structure from the projects URLs:
 - Project's repository: `#{namespace}/#{project_name}.git`
 - Project's wiki: `#{namespace}/#{project_name}.wiki.git`
 
-This structure made it simple to migrate from existing solutions to GitLab and
-easy for Administrators to find where the repository is stored.
+This structure enables you to migrate from existing solutions to GitLab, and
+for Administrators to find where the repository is stored.
 
-On the other hand this has some drawbacks:
+This approach also has some drawbacks:
 
 Storage location concentrates a huge number of top-level namespaces. The
 impact can be reduced by the introduction of
@@ -211,4 +211,4 @@ is at that same URL today.
 
 Any change in the URL needs to be reflected on disk (when groups / users or
 projects are renamed). This can add a lot of load in big installations,
-especially if using any type of network based filesystem.
+especially if using any type of network based file system.

doc/administration/snippets/index.md

@@ -18,7 +18,7 @@ abuse of the feature. The default value is **52428800 Bytes** (50 MB).
 
 ### How does it work?
 
-The content size limit will be applied when a snippet is created or updated.
+The content size limit is applied when a snippet is created or updated.
 
 This limit doesn't affect existing snippets until they're updated and their
 content changes.
@@ -60,8 +60,8 @@ To retrieve the current value, start the Rails console and run:
 
 #### Through the API
 
-The process to set the snippets size limit through the Application Settings API is
-exactly the same as you would do to [update any other setting](../../api/settings.md#change-application-settings).
+To set the snippets size limit through the Application Settings API (similar to
+[updating any other setting](../../api/settings.md#change-application-settings)), use this command:
 
 ```shell
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?snippet_size_limit=52428800"

doc/administration/wikis/index.md

@@ -18,24 +18,24 @@ abuse of the feature. The default value is **52428800 Bytes** (50 MB).
 
 ### How does it work?
 
-The content size limit will be applied when a wiki page is created or updated
-through the GitLab UI or API. Local changes pushed via Git will not be validated.
+The content size limit is applied when a wiki page is created or updated
+through the GitLab UI or API. Local changes pushed via Git are not validated.
 
-In order not to break any existing wiki pages, the limit doesn't have any
-effect on them until a wiki page is edited again and the content changes.
+To break any existing wiki pages, the limit doesn't take effect until a wiki page
+is edited again and the content changes.
 
 ### Wiki page content size limit configuration
 
 This setting is not available through the [Admin Area settings](../../user/admin_area/settings/index.md).
-In order to configure this setting, use either the Rails console
+To configure this setting, use either the Rails console
 or the [Application settings API](../../api/settings.md).
 
 NOTE:
-The value of the limit **must** be in bytes. The minimum value is 1024 bytes.
+The value of the limit must be in bytes. The minimum value is 1024 bytes.
 
 #### Through the Rails console
 
-The steps to configure this setting through the Rails console are:
+To configure this setting through the Rails console:
 
 1. Start the Rails console:
 
@@ -61,14 +61,14 @@ To retrieve the current value, start the Rails console and run:
 
 #### Through the API
 
-The process to set the wiki page size limit through the Application Settings API is
-exactly the same as you would do to [update any other setting](../../api/settings.md#change-application-settings).
+To set the wiki page size limit through the Application Settings API, use a command,
+as you would to [update any other setting](../../api/settings.md#change-application-settings):
 
 ```shell
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings?wiki_page_max_content_bytes=52428800"
 ```
 
-You can also use the API to [retrieve the current value](../../api/settings.md#get-current-application-settings).
+You can also use the API to [retrieve the current value](../../api/settings.md#get-current-application-settings):
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/application/settings"

doc/integration/README.md

@@ -25,7 +25,7 @@ GitLab can be configured to authenticate access requests with the following auth
 - Enable sign in via [LDAP](../administration/auth/ldap/index.md).
 - Enable [OAuth2 provider](oauth_provider.md) application creation.
 - Use [OmniAuth](omniauth.md) to enable sign in via Twitter, GitHub, GitLab.com, Google,
-  Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure or Authentiq ID.
+  Bitbucket, Facebook, Shibboleth, SAML, Crowd, Azure, or Authentiq ID.
 - Use GitLab as an [OpenID Connect](openid_connect_provider.md) identity provider.
 - Authenticate to [Vault](vault.md) through GitLab OpenID Connect.
 - Configure GitLab as a [SAML](saml.md) 2.0 Service Provider.

doc/integration/bitbucket.md

@@ -10,8 +10,8 @@ NOTE:
 Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an
 earlier version, you must explicitly enable it.
 
-You can set up Bitbucket.org as an OAuth2 provider so that you can use your
-Bitbucket.org account credentials to sign into GitLab or import your projects from
+You can set up Bitbucket.org as an OAuth2 provider to use your
+Bitbucket.org account credentials to sign in to GitLab, or import your projects from
 Bitbucket.org.
 
 - To use Bitbucket.org as an OmniAuth provider, follow the

doc/integration/github.md

@@ -6,9 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Integrate your GitLab instance with GitHub
 
-You can integrate your GitLab instance with GitHub.com and GitHub Enterprise to
-enable users to import projects from GitHub or sign in to your GitLab instance
-with your GitHub account.
+You can integrate your GitLab instance with GitHub.com and GitHub Enterprise. This integration
+enables users to import projects from GitHub, or sign in to your GitLab instance
+with their GitHub account.
 
 ## Enabling GitHub OAuth
 
@@ -24,7 +24,7 @@ To prevent an [OAuth2 covert redirect](https://oauth.net/advisories/2014-1-cover
 
 See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings.
 
-After you have configured the GitHub provider, you need the following information, which you must substitute in the GitLab configuration file, in the steps shown next.
+After you have configured the GitHub provider, you need the following information. You must substitute that information in the GitLab configuration file in these next steps.
 
 | Setting from GitHub  | Substitute in the GitLab configuration file  | Description |
 |:---------------------|:---------------------------------------------|:------------|

doc/integration/gitlab.md

@@ -11,7 +11,7 @@ Import projects from GitLab.com and login to your GitLab instance with your GitL
 To enable the GitLab.com OmniAuth provider you must register your application with GitLab.com.
 GitLab.com generates an application ID and secret key for you to use.
 
-1. Sign in to GitLab.com
+1. Sign in to GitLab.com.
 
 1. On the upper right corner, click on your avatar and go to your **Settings**.
 

doc/integration/gmail_action_buttons_for_gitlab.md

@@ -24,6 +24,11 @@ In particular, note:
     (order of hundred emails a day minimum to Gmail) for a few weeks at least".
   - Have a very low rate of spam complaints from users.
 - Emails must be authenticated via DKIM or SPF.
-- Before sending the final form ("Gmail Schema Whitelist Request"), you must send a real email from your production server. This means that you must find a way to send this email from the email address you are registering. You can do this by, for example, forwarding the real email from the email address you are registering or going into the rails console on the GitLab server and triggering the email sending from there.
+- Before sending the final form ("Gmail Schema Whitelist Request"), you must
+  send a real email from your production server. This means that you must find
+  a way to send this email from the email address you are registering. You can
+  do this by forwarding the real email from the email address you are
+  registering. You can also go into the Rails console on the GitLab server and
+  trigger sending the email from there.
 
 You can check how it looks going through all the steps laid out in the "Registering with Google" doc in [this GitLab.com issue](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/1517).

doc/integration/jenkins.md

@@ -64,7 +64,7 @@ Grant a GitLab user access to the select GitLab projects.
 1. Grant the user permission to the GitLab projects.
 
    If you're integrating Jenkins with many GitLab projects, consider granting the user global
-   Admin permission. Otherwise, add the user to each project, and grant Developer permission.
+   Administrator permission. Otherwise, add the user to each project, and grant Developer permission.
 
 ## Configure GitLab API access
 
@@ -166,7 +166,7 @@ to integrate GitLab and Jenkins.
 1. In the configuration of your Jenkins job, in the GitLab configuration section, click **Advanced**.
 1. Click the **Generate** button under the **Secret Token** field.
 1. Copy the resulting token, and save the job configuration.
-1. In GitLab, create a webhook for your project, enter the trigger URL (e.g. `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field.
+1. In GitLab, create a webhook for your project, enter the trigger URL (such as `https://JENKINS_URL/project/YOUR_JOB`) and paste the token in the **Secret Token** field.
 1. After you add the webhook, click the **Test** button, and it should succeed.
 
 ## Troubleshooting
@@ -205,8 +205,8 @@ which is set to 10 seconds by default.
 To fix this the `gitlab_rails['webhook_timeout']` value must be increased
 in the `gitlab.rb` configuration file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md).
 
-If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this
-could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered):
+If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`),
+[webhook requests may be timing out](../user/project/integrations/webhooks.md#webhook-fails-or-multiple-webhook-requests-are-triggered):
 
 ```plaintext
 2019-10-25_04:22:41.25630 2019-10-25T04:22:41.256Z 1584 TID-ovowh4tek WebHookWorker JID-941fb7f40b69dff3d833c99b INFO: start

doc/integration/jira_development_panel.md

@@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2381) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.0.
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/233149) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.4.
 
-The Jira Development Panel integration allows you to reference Jira issues within GitLab, displaying
+The Jira Development Panel integration allows you to reference Jira issues in GitLab, displaying
 activity in the [Development panel](https://support.atlassian.com/jira-software-cloud/docs/view-development-information-for-an-issue/)
 in the issue.
 
@@ -35,7 +35,7 @@ See the [Configuration](#configuration) section for details.
 
 With this integration, you can access related GitLab merge requests, branches, and commits directly from a Jira issue, reflecting your work in GitLab. From the Development panel, you can open a detailed view and take actions including creating a new merge request from a branch. For more information, see [Usage](#usage).
 
-This integration connects all GitLab projects to projects in the Jira instance within either:
+This integration connects all GitLab projects to projects in the Jira instance in either:
 
 - A top-level group. A top-level GitLab group is one that does not have any parent group itself. All
   the projects of that top-level group, as well as projects of the top-level group's subgroups nesting
@@ -211,7 +211,7 @@ The requested scope is invalid, unknown, or malformed.
 
 Potential resolutions:
 
-- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setup](#jira-dvcs-connector-setup) includes `scope=api` within the query string.
+- Verify the URL shown in the browser after being redirected from Jira in step 5 of [Jira DVCS Connector Setup](#jira-dvcs-connector-setup) includes `scope=api` in the query string.
 - If `scope=api` is missing from the URL, return to [GitLab account configuration](#gitlab-account-configuration-for-dvcs) and ensure the application you created in step 1 has the `api` box checked under scopes.
 
 ##### Jira error adding account and no repositories listed
@@ -314,6 +314,6 @@ For more information on using Jira Smart Commits to track time against an issue,
 
 ## Limitations
 
-This integration is currently not supported on GitLab instances under a
+This integration is not supported on GitLab instances under a
 [relative URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab).
 For example, `http://example.com/gitlab`.

doc/integration/oauth2_generic.md

@@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Sign into GitLab with (almost) any OAuth2 provider
 
-The `omniauth-oauth2-generic` gem allows Single Sign On between GitLab and your own OAuth2 provider
+The `omniauth-oauth2-generic` gem allows Single Sign-On between GitLab and your own OAuth2 provider
 (or any OAuth2 provider compatible with this gem)
 
 This strategy is designed to allow configuration of the simple OmniAuth SSO process outlined below:

doc/integration/oauth_provider.md

@@ -20,15 +20,14 @@ If you want to use:
 ## Introduction to OAuth
 
 [OAuth](https://oauth.net/2/) provides to client applications a 'secure delegated access' to server
-resources on behalf of a resource owner. In fact, OAuth allows an authorization
+resources on behalf of a resource owner. OAuth allows an authorization
 server to issue access tokens to third-party clients with the approval of the
 resource owner, or the end-user.
 
 OAuth is mostly used as a Single Sign-On service (SSO), but you can find a
 lot of different uses for this functionality. For example, you can allow users
-to sign in to your application with their GitLab.com account, or GitLab.com
-can be used for authentication to your GitLab instance
-(see [GitLab OmniAuth](gitlab.md)).
+to sign in to your application with their GitLab.com account. You can also use GitLab.com
+for authentication to your GitLab instance (see [GitLab OmniAuth](gitlab.md)).
 
 The 'GitLab Importer' feature is also using the OAuth protocol to give access
 to repositories without sharing user credentials to your GitLab.com account.
@@ -37,7 +36,7 @@ GitLab supports two ways of adding a new OAuth2 application to an instance. You
 can either add an application as a regular user or add it in the Admin Area.
 What this means is that GitLab can actually have instance-wide and a user-wide
 applications. There is no difference between them except for the different
-permission levels they are set (user/admin). The default callback URL is
+permission levels they are set (user or administrator). The default callback URL is
 `http://your-gitlab.example.com/users/auth/gitlab/callback`
 
 ## Adding an application through the profile
@@ -64,7 +63,7 @@ connects to GitLab.
 To create an application that does not belong to a certain user, you can create
 it from the Admin Area.
 
-![OAuth admin_applications](img/oauth_provider_admin_application.png)
+![OAuth administrator applications](img/oauth_provider_admin_application.png)
 
 You're also able to mark an application as _trusted_ when creating it through the Admin Area. By doing that,
 the user authorization step is automatically skipped for this application.
@@ -88,9 +87,9 @@ application can perform. The available scopes are depicted in the following tabl
 | `write_repository` | Grants read-write access to repositories on private projects using Git-over-HTTP (not using the API). |
 | `read_registry`    |  Grants read-only access to container registry images on private projects. |
 | `write_registry`   | Grants read-only access to container registry images on private projects. |
-| `sudo`             | Grants permission to perform API actions as any user in the system, when authenticated as an admin user. |
+| `sudo`             | Grants permission to perform API actions as any user in the system, when authenticated as an administrator user. |
 | `openid`           | Grants permission to authenticate with GitLab using [OpenID Connect](openid_connect_provider.md). Also gives read-only access to the user's profile and group memberships. |
 | `profile`          |  Grants read-only access to the user's profile data using [OpenID Connect](openid_connect_provider.md). |
 | `email`            |  Grants read-only access to the user's primary email address using [OpenID Connect](openid_connect_provider.md). |
 
-At any time you can revoke any access by just clicking **Revoke**.
+At any time you can revoke any access by clicking **Revoke**.

doc/integration/omniauth.md

@@ -55,7 +55,7 @@ earlier version, you must explicitly enable it.
 
 - `allow_single_sign_on` allows you to specify the providers you want to allow to
   automatically create an account. It defaults to `false`. If `false` users must
-  be created manually or they can't sign in via OmniAuth.
+  be created manually or they can't sign in by using OmniAuth.
 - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](../administration/auth/ldap/index.md)
   integration enabled. It defaults to `false`. When enabled, users automatically
   created through an OmniAuth provider have their LDAP identity created in GitLab as well.
@@ -66,7 +66,7 @@ earlier version, you must explicitly enable it.
 NOTE:
 If you set `block_auto_created_users` to `false`, make sure to only
 define providers under `allow_single_sign_on` that you are able to control, like
-SAML, Shibboleth, Crowd or Google, or set it to `false` otherwise any user on
+SAML, Shibboleth, Crowd, or Google, or set it to `false` otherwise any user on
 the Internet can successfully sign in to your GitLab without
 administrative approval.
 
@@ -170,8 +170,8 @@ omniauth:
 
 > Introduced in GitLab 8.7.
 
-You can define which OmniAuth providers you want to be `external` so that all users
-**creating accounts, or logging in via these providers** can't have
+You can define which OmniAuth providers you want to be `external`. Users
+creating accounts, or logging in by using these `external` providers cannot have
 access to internal projects. You must use the full name of the provider,
 like `google_oauth2` for Google. Refer to the examples for the full names of the
 supported providers.
@@ -200,9 +200,9 @@ NOTE:
 The following information only applies for installations from source.
 
 GitLab uses [OmniAuth](https://github.com/omniauth/omniauth) for authentication and already ships
-with a few providers pre-installed (e.g. LDAP, GitHub, Twitter). But sometimes that
-is not enough and you need to integrate with other authentication solutions. For
-these cases you can use the OmniAuth provider.
+with a few providers pre-installed, such as LDAP, GitHub, and Twitter. You may also
+need to integrate with other authentication solutions. For
+these cases, you can use the OmniAuth provider.
 
 ### Steps
 
@@ -251,10 +251,10 @@ we'd like to at least help those with specific needs.
 
 > Introduced in GitLab 8.8.
 
-Administrators are able to enable or disable Sign In via some OmniAuth providers.
+Administrators are able to enable or disable Sign In by using some OmniAuth providers.
 
 NOTE:
-By default Sign In is enabled via all the OAuth Providers that have been configured in `config/gitlab.yml`.
+By default Sign In is enabled by using all the OAuth Providers that have been configured in `config/gitlab.yml`.
 
 In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings -> Sign-in Restrictions section -> Enabled OAuth Sign-In sources and select the providers you want to enable or disable.
 
@@ -345,7 +345,7 @@ omniauth:
 
 Keep in mind that every sign-in attempt is redirected to the OmniAuth
 provider; you can't sign in using local credentials. Ensure at least
-one of the OmniAuth users has admin permissions.
+one of the OmniAuth users has administrator permissions.
 
 You may also bypass the auto sign in feature by browsing to
 `https://gitlab.example.com/users/sign_in?auto_sign_in=false`.

doc/integration/openid_connect_provider.md

@@ -12,11 +12,13 @@ to sign in to other services.
 ## Introduction to OpenID Connect
 
 [OpenID Connect](https://openid.net/connect/) \(OIDC) is a simple identity layer on top of the
-OAuth 2.0 protocol. It allows clients to verify the identity of the end-user
-based on the authentication performed by GitLab, as well as to obtain
-basic profile information about the end-user in an interoperable and
-REST-like manner. OIDC performs many of the same tasks as OpenID 2.0,
-but does so in a way that is API-friendly, and usable by native and
+OAuth 2.0 protocol. It allows clients to:
+
+- Verify the identity of the end-user based on the authentication performed by GitLab.
+- Obtain basic profile information about the end-user in an interoperable and REST-like manner.
+
+OIDC performs many of the same tasks as OpenID 2.0,
+but does so in a way that is API-friendly and usable by native and
 mobile applications.
 
 On the client side, you can use [OmniAuth::OpenIDConnect](https://github.com/jjbohn/omniauth-openid-connect/) for Rails
@@ -34,7 +36,7 @@ is select the `openid` scope in the application settings.
 
 ## Shared information
 
-Currently the following user information is shared with clients:
+The following user information is shared with clients:
 
 | Claim            | Type      | Description |
 |:-----------------|:----------|:------------|

doc/integration/recaptcha.md

@@ -14,7 +14,7 @@ to confirm that a real user, not a bot, is attempting to create an account.
 
 To use reCAPTCHA, first you must create a site and private key.
 
-1. Go to the URL: <https://www.google.com/recaptcha/admin>.
+1. Go to the [Google reCAPTCHA page](https://www.google.com/recaptcha/admin).
 1. Fill out the form necessary to obtain reCAPTCHA v2 keys.
 1. Log in to your GitLab server, with administrator credentials.
 1. Go to Reporting Applications Settings in the Admin Area (`admin/application_settings/reporting`).
@@ -26,7 +26,7 @@ To use reCAPTCHA, first you must create a site and private key.
    return `recaptcha_html`.
 
 NOTE:
-Make sure you are viewing an issuable in a project that is public, and if you're working with an issue, the issue is public.
+Make sure you are viewing an issuable in a project that is public. If you're working with an issue, the issue is public.
 
 ## Enabling reCAPTCHA for user logins via passwords
 

doc/integration/salesforce.md

@@ -86,4 +86,6 @@ Click the icon to begin the authentication process. Salesforce asks the user to
 If everything goes well, the user is returned to GitLab and is signed in.
 
 NOTE:
-GitLab requires the email address of each new user. Once the user is logged in using Salesforce, GitLab redirects the user to the profile page where they must provide the email and verify the email.
+GitLab requires the email address of each new user. After the user is signed in
+using Salesforce, GitLab redirects the user to the profile page where they must
+provide the email and verify the email.

doc/integration/shibboleth.md

@@ -10,17 +10,17 @@ NOTE:
 The preferred approach for integrating a Shibboleth authentication system
 with GitLab 10 or newer is to use the [GitLab SAML integration](saml.md). This documentation is for Omnibus GitLab 9.x installs or older.
 
-In order to enable Shibboleth support in GitLab we need to use Apache instead of NGINX (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package). Apache uses mod_shib2 module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider.
+To enable Shibboleth support in GitLab we need to use Apache instead of NGINX. (It may be possible to use NGINX, however this is difficult to configure using the bundled NGINX provided in the Omnibus GitLab package.) Apache uses `mod_shib2` module for Shibboleth authentication and can pass attributes as headers to OmniAuth Shibboleth provider.
 
 To enable the Shibboleth OmniAuth provider you must configure Apache Shibboleth module.
 The installation and configuration of the module itself is out of the scope of this document.
-Check <https://wiki.shibboleth.net/confluence/display/SP3/Apache> for more information.
+Check [the Shibboleth documentation](https://wiki.shibboleth.net/confluence/display/SP3/Apache) for more information.
 
 You can find Apache configuration in [GitLab Recipes](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache).
 
 The following changes are needed to enable Shibboleth:
 
-1. Protect OmniAuth Shibboleth callback URL:
+1. Protect the OmniAuth Shibboleth callback URL:
 
    ```apache
    <Location /users/auth/shibboleth/callback>
@@ -53,7 +53,7 @@ The following changes are needed to enable Shibboleth:
    ```
 
    NOTE:
-   Starting from GitLab 11.4, OmniAuth is enabled by default. If you're using an
+   In GitLab versions 11.4 and later, OmniAuth is enabled by default. If you're using an
    earlier version, you must explicitly enable it in `/etc/gitlab/gitlab.rb`.
 
 1. In addition, add Shibboleth to `/etc/gitlab/gitlab.rb` as an OmniAuth provider.
@@ -100,7 +100,7 @@ The following changes are needed to enable Shibboleth:
 1. [Reconfigure](../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../administration/restart_gitlab.md#installations-from-source) GitLab for the changes to take effect if you
    installed GitLab via Omnibus or from source respectively.
 
-On the sign in page, there should now be a "Sign in with: Shibboleth" icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in.
+On the sign in page, there should now be a **Sign in with: Shibboleth** icon below the regular sign in form. Click the icon to begin the authentication process. You are redirected to IdP server (depends on your Shibboleth module configuration). If everything goes well the user is returned to GitLab and is signed in.
 
 ## Apache 2.4 / GitLab 8.6 update
 

doc/integration/slash_commands.md

@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > The `run` command was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/24780) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9.
 
-Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). Simply type the command as a message in your chat client to activate it.
+Slash commands in Mattermost and Slack allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires an [integration configuration](../user/project/integrations/slack_slash_commands.md). Type the command as a message in your chat client to activate it.
 
 Commands are scoped to a project, with a trigger term that is specified during configuration.
 
@@ -28,8 +28,8 @@ Taking the trigger term as `project-name`, the commands are:
 | `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment |
 | `/project-name run <job name> <arguments>` | Execute [ChatOps](../ci/chatops/README.md) job `<job name>` on `master` |
 
-Note that if you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for
-your GitLab.com projects, you need to [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage).
+If you are using the [GitLab Slack application](../user/project/integrations/gitlab_slack_application.md) for
+your GitLab.com projects, [add the `gitlab` keyword at the beginning of the command](../user/project/integrations/gitlab_slack_application.md#usage).
 
 ## Issue commands
 

doc/integration/sourcegraph.md

@@ -25,7 +25,7 @@ you can choose to enable Sourcegraph [through your user preferences](#enable-sou
 
 ## Set up for self-managed GitLab instances **(CORE ONLY)**
 
-Before you can enable Sourcegraph code intelligence in GitLab you will need to:
+Before you can enable Sourcegraph code intelligence in GitLab you must:
 
 - Enable the `sourcegraph` feature flag for your GitLab instance.
 - Configure a Sourcegraph instance with your GitLab instance as an external service.
@@ -33,7 +33,7 @@ Before you can enable Sourcegraph code intelligence in GitLab you will need to:
 ### Enable the Sourcegraph feature flag
 
 NOTE:
-If you are running a self-managed instance, the Sourcegraph integration will not be available
+If you are running a self-managed instance, the Sourcegraph integration is unavailable
 unless the feature flag `sourcegraph` is enabled. This can be done from the Rails console
 by instance administrators.
 
@@ -64,7 +64,7 @@ Feature.enable(:sourcegraph, Project.find_by_full_path('my_group/my_project'))
 
 If you are new to Sourcegraph, head over to the [Sourcegraph installation documentation](https://docs.sourcegraph.com/admin) and get your instance up and running.
 
-If you are using an HTTPS connection to GitLab, you will need to [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance.
+If you are using an HTTPS connection to GitLab, you must [configure HTTPS](https://docs.sourcegraph.com/admin/http_https_configuration) for your Sourcegraph instance.
 
 ### Connect your Sourcegraph instance to your GitLab instance
 
@@ -79,9 +79,9 @@ You can skip this step if you already have your GitLab repositories searchable i
 1. In GitLab, go to **Admin Area > Settings > General**.
 1. Expand the **Sourcegraph** configuration section.
 1. Check **Enable Sourcegraph**.
-1. Set the Sourcegraph URL to your Sourcegraph instance, e.g., `https://sourcegraph.example.com`.
+1. Set the Sourcegraph URL to your Sourcegraph instance, such as `https://sourcegraph.example.com`.
 
-![Sourcegraph admin settings](img/sourcegraph_admin_v12_5.png)
+![Sourcegraph administration settings](img/sourcegraph_admin_v12_5.png)
 
 ## Enable Sourcegraph in user preferences
 
@@ -95,7 +95,7 @@ If a GitLab administrator has enabled Sourcegraph, you can enable this feature i
 
 ## Using Sourcegraph code intelligence
 
-Once enabled, participating projects will have a code intelligence popover available in
+Once enabled, participating projects display a code intelligence popover available in
 the following code views:
 
 - Merge request diffs
@@ -114,7 +114,7 @@ When visiting one of these views, you can now hover over a code reference to see
 
 Sourcegraph powered code intelligence is available for all public projects on GitLab.com.
 
-Support for private projects is currently not available for GitLab.com;
+Support for private projects is not yet available for GitLab.com;
 follow the epic [&2201](https://gitlab.com/groups/gitlab-org/-/epics/2201)
 for updates.
 
@@ -122,7 +122,7 @@ for updates.
 
 ### Sourcegraph isn't working
 
-If you enabled Sourcegraph for your project but still it doesn't look like it's working, it might be because Sourcegraph has not indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project.
+If you enabled Sourcegraph for your project but it isn't working, Sourcegraph may not have indexed the project yet. You can check for Sourcegraph's availability of your project by visiting `https://sourcegraph.com/gitlab.com/<project-path>`replacing `<project-path>` with the path to your GitLab project.
 
 ## Sourcegraph and Privacy
 
@@ -130,5 +130,5 @@ From Sourcegraph's [extension documentation](https://docs.sourcegraph.com/integr
 engine behind the native GitLab integration:
 
 > Sourcegraph integrations never send any logs, pings, usage statistics, or telemetry to Sourcegraph.com.
-> They will only connect to Sourcegraph.com as required to provide code intelligence or other functionality on public code.
+> They connect only to Sourcegraph.com as required to provide code intelligence or other functionality on public code.
 > As a result, no private code, private repository names, usernames, or any other specific data is sent to Sourcegraph.com.

ee/app/services/epics/issue_promote_service.rb

@@ -32,8 +32,10 @@ module Epics
     end
 
     def track_event
+      context = ::Gitlab::Tracking::StandardContext.new(namespace: @parent_group, project: issue.project, user: current_user)
+
       ::Gitlab::Tracking.event('epics', 'promote', property: 'issue_id', value: original_entity.id,
-                               standard_context: ::Gitlab::Tracking::StandardContext.new(namespace: @parent_group, project: issue.project))
+                               standard_context: context)
     end
 
     def create_new_entity

ee/spec/services/epics/issue_promote_service_spec.rb

@@ -65,7 +65,7 @@ RSpec.describe Epics::IssuePromoteService, :aggregate_failures do
             subject.execute(issue)
 
             expect_snowplow_event(category: 'epics', action: 'promote', property: 'issue_id', value: issue.id,
-                                  standard_context: { namespace: group, project: project })
+                                  standard_context: { namespace: group, project: project, user: user })
           end
 
           it 'creates a new epic with correct attributes' do
@@ -201,7 +201,7 @@ RSpec.describe Epics::IssuePromoteService, :aggregate_failures do
             expect(epic.notes.where(discussion_id: discussion.discussion_id).count).to eq(0)
             expect(issue.notes.where(discussion_id: discussion.discussion_id).count).to eq(1)
             expect_snowplow_event(category: 'epics', action: 'promote', property: 'issue_id', value: issue.id,
-                                  standard_context: { namespace: group, project: project })
+                                  standard_context: { namespace: group, project: project, user: user })
           end
 
           it 'copies note attachments' do
@@ -211,7 +211,7 @@ RSpec.describe Epics::IssuePromoteService, :aggregate_failures do
 
             expect(epic.notes.user.first.attachment).to be_kind_of(AttachmentUploader)
             expect_snowplow_event(category: 'epics', action: 'promote', property: 'issue_id', value: issue.id,
-                                  standard_context: { namespace: group, project: project })
+                                  standard_context: { namespace: group, project: project, user: user })
           end
         end
 

lib/bulk_imports/pipeline/runner.rb

@@ -31,16 +31,16 @@ module BulkImports
 
       private # rubocop:disable Lint/UselessAccessModifier
 
-      def run_pipeline_step(type, class_name, context)
+      def run_pipeline_step(step, class_name, context)
         raise MarkedAsFailedError if marked_as_failed?(context)
 
-        info(context, type => class_name)
+        info(context, step => class_name)
 
         yield
       rescue MarkedAsFailedError
-        log_skip(context, type => class_name)
+        log_skip(context, step => class_name)
       rescue => e
-        log_import_failure(e, context)
+        log_import_failure(e, step, context)
 
         mark_as_failed(context) if abort_on_failure?
       end
@@ -72,10 +72,11 @@ module BulkImports
         info(context, log)
       end
 
-      def log_import_failure(exception, context)
+      def log_import_failure(exception, step, context)
         attributes = {
           bulk_import_entity_id: context.entity.id,
           pipeline_class: pipeline,
+          pipeline_step: step,
           exception_class: exception.class.to_s,
           exception_message: exception.message.truncate(255),
           correlation_id_value: Labkit::Correlation::CorrelationId.current_or_new_id

lib/gitlab/tracking/standard_context.rb

@@ -5,9 +5,7 @@ module Gitlab
     class StandardContext
       GITLAB_STANDARD_SCHEMA_URL = 'iglu:com.gitlab/gitlab_standard/jsonschema/1-0-2'.freeze
 
-      def initialize(namespace: nil, project: nil, **data)
-        @namespace = namespace
-        @project = project
+      def initialize(namespace: nil, project: nil, user: nil, **data)
         @data = data
       end
 

locale/gitlab.pot

@@ -16406,6 +16406,9 @@ msgstr ""
 msgid "KeyboardShortcuts|Global Shortcuts"
 msgstr ""
 
+msgid "KeyboardShortcuts|Toggle GitLab Next"
+msgstr ""
+
 msgid "KeyboardShortcuts|Toggle the Performance Bar"
 msgstr ""
 
@@ -29907,6 +29910,9 @@ msgstr ""
 msgid "Today"
 msgstr ""
 
+msgid "Toggle GitLab Next"
+msgstr ""
+
 msgid "Toggle Markdown preview"
 msgstr ""
 

spec/lib/bulk_imports/pipeline/runner_spec.rb

@@ -103,6 +103,7 @@ RSpec.describe BulkImports::Pipeline::Runner do
 
           expect(failure).to be_present
           expect(failure.pipeline_class).to eq('BulkImports::MyPipeline')
+          expect(failure.pipeline_step).to eq('extractor')
           expect(failure.exception_class).to eq('StandardError')
           expect(failure.exception_message).to eq('Error!')
         end