Merge branch 'security-ag-contribution-analytics' into 'master'

Hide Contribution Analytics from non-group members

See merge request gitlab-org/security/gitlab!58

Gemfile

@@ -419,7 +419,8 @@ end
 
 gem 'octokit', '~> 4.15'
 
-gem 'mail_room', '~> 0.10.0'
+# https://gitlab.com/gitlab-org/gitlab/issues/207207
+gem 'gitlab-mail_room', '~> 0.0.2', require: 'mail_room'
 
 gem 'email_reply_trimmer', '~> 0.1'
 gem 'html2text'

Gemfile.lock

@@ -388,6 +388,7 @@ GEM
       opentracing (~> 0.4)
       redis (> 3.0.0, < 5.0.0)
     gitlab-license (1.0.0)
+    gitlab-mail_room (0.0.2)
     gitlab-markup (1.7.0)
     gitlab-net-dns (0.9.1)
     gitlab-puma (4.3.1.gitlab.2)
@@ -616,7 +617,6 @@ GEM
     lumberjack (1.0.13)
     mail (2.7.1)
       mini_mime (>= 0.1.1)
-    mail_room (0.10.0)
     marcel (0.3.3)
       mimemagic (~> 0.3.2)
     marginalia (1.8.0)
@@ -1235,6 +1235,7 @@ DEPENDENCIES
   gitlab-chronic (~> 0.10.5)
   gitlab-labkit (= 0.10.0)
   gitlab-license (~> 1.0)
+  gitlab-mail_room (~> 0.0.2)
   gitlab-markup (~> 1.7.0)
   gitlab-net-dns (~> 0.9.1)
   gitlab-puma (~> 4.3.1.gitlab.2)
@@ -1284,7 +1285,6 @@ DEPENDENCIES
   loofah (~> 2.2)
   lru_redux
   mail (= 2.7.1)
-  mail_room (~> 0.10.0)
   marginalia (~> 1.8.0)
   memory_profiler (~> 0.9)
   method_source (~> 0.8)

app/assets/javascripts/diffs/components/diff_table_cell.vue

@@ -166,6 +166,7 @@ export default {
         :href="lineHref"
         @click="setHighlightedRow(lineCode)"
       >
+        {{ lineNumber }}
       </a>
       <diff-gutter-avatars
         v-if="shouldShowAvatarsOnGutter"

app/assets/javascripts/notes/stores/getters.js

@@ -28,6 +28,8 @@ export const getUserData = state => state.userData || {};
 
 export const getUserDataByProp = state => prop => state.userData && state.userData[prop];
 
+export const descriptionVersion = state => state.descriptionVersion;
+
 export const notesById = state =>
   state.discussions.reduce((acc, note) => {
     note.notes.every(n => Object.assign(acc, { [n.id]: n }));

app/assets/javascripts/vue_shared/components/notes/system_note.vue

@@ -54,8 +54,8 @@ export default {
     };
   },
   computed: {
-    ...mapGetters(['targetNoteHash']),
-    ...mapState(['descriptionVersion', 'isLoadingDescriptionVersion']),
+    ...mapGetters(['targetNoteHash', 'descriptionVersion']),
+    ...mapState(['isLoadingDescriptionVersion']),
     noteAnchorId() {
       return `note_${this.note.id}`;
     },

app/assets/stylesheets/pages/diff.scss

@@ -485,10 +485,6 @@ table.code {
           }
         }
       }
-
-      &:not(.js-unfold-bottom) a::before {
-        content: attr(data-linenumber);
-      }
     }
 
     &.line_content {

app/models/concerns/cache_markdown_field.rb

@@ -20,6 +20,10 @@ module CacheMarkdownField
     false
   end
 
+  def can_cache_field?(field)
+    true
+  end
+
   # Returns the default Banzai render context for the cached markdown field.
   def banzai_render_context(field)
     raise ArgumentError.new("Unknown field: #{field.inspect}") unless
@@ -38,17 +42,23 @@ module CacheMarkdownField
     context
   end
 
-  # Update every column in a row if any one is invalidated, as we only store
-  # one version per row
-  def refresh_markdown_cache
+  def rendered_field_content(markdown_field)
+    return unless can_cache_field?(markdown_field)
+
     options = { skip_project_check: skip_project_check? }
+    Banzai::Renderer.cacheless_render_field(self, markdown_field, options)
+  end
 
+  # Update every applicable column in a row if any one is invalidated, as we only store
+  # one version per row
+  def refresh_markdown_cache
     updates = cached_markdown_fields.markdown_fields.map do |markdown_field|
       [
         cached_markdown_fields.html_field(markdown_field),
-        Banzai::Renderer.cacheless_render_field(self, markdown_field, options)
+        rendered_field_content(markdown_field)
       ]
     end.to_h
+
     updates['cached_markdown_version'] = latest_cached_markdown_version
 
     updates.each { |field, data| write_markdown_field(field, data) }

app/models/group.rb

@@ -406,11 +406,15 @@ class Group < Namespace
   end
 
   def ci_variables_for(ref, project)
-    list_of_ids = [self] + ancestors
-    variables = Ci::GroupVariable.where(group: list_of_ids)
-    variables = variables.unprotected unless project.protected_for?(ref)
-    variables = variables.group_by(&:group_id)
-    list_of_ids.reverse.flat_map { |group| variables[group.id] }.compact
+    cache_key = "ci_variables_for:group:#{self&.id}:project:#{project&.id}:ref:#{ref}"
+
+    ::Gitlab::SafeRequestStore.fetch(cache_key) do
+      list_of_ids = [self] + ancestors
+      variables = Ci::GroupVariable.where(group: list_of_ids)
+      variables = variables.unprotected unless project.protected_for?(ref)
+      variables = variables.group_by(&:group_id)
+      list_of_ids.reverse.flat_map { |group| variables[group.id] }.compact
+    end
   end
 
   def group_member(user)

app/models/project.rb

@@ -1963,6 +1963,14 @@ class Project < ApplicationRecord
   end
 
   def ci_variables_for(ref:, environment: nil)
+    cache_key = "ci_variables_for:project:#{self&.id}:ref:#{ref}:environment:#{environment}"
+
+    ::Gitlab::SafeRequestStore.fetch(cache_key) do
+      uncached_ci_variables_for(ref: ref, environment: environment)
+    end
+  end
+
+  def uncached_ci_variables_for(ref:, environment: nil)
     result = if protected_for?(ref)
                variables
              else

app/models/concerns/resource_event_tools.rb → app/models/resource_event.rb

 # frozen_string_literal: true
 
-module ResourceEventTools
-  extend ActiveSupport::Concern
+class ResourceEvent < ApplicationRecord
+  include Gitlab::Utils::StrongMemoize
+  include Importable
 
-  included do
-    belongs_to :user
+  self.abstract_class = true
 
-    validates :user, presence: { unless: :importing? }, on: :create
+  validates :user, presence: { unless: :importing? }, on: :create
 
-    validate :exactly_one_issuable
+  belongs_to :user
 
-    scope :created_after, ->(time) { where('created_at > ?', time) }
+  scope :created_after, ->(time) { where('created_at > ?', time) }
+
+  def discussion_id
+    strong_memoize(:discussion_id) do
+      Digest::SHA1.hexdigest(discussion_id_key.join("-"))
+    end
+  end
+
+  private
+
+  def discussion_id_key
+    [self.class.name, created_at, user_id]
   end
 
   def exactly_one_issuable

app/models/resource_label_event.rb

 # frozen_string_literal: true
 
-class ResourceLabelEvent < ApplicationRecord
-  include Importable
-  include Gitlab::Utils::StrongMemoize
+class ResourceLabelEvent < ResourceEvent
   include CacheMarkdownField
-  include ResourceEventTools
 
   cache_markdown_field :reference
 
@@ -13,8 +10,11 @@ class ResourceLabelEvent < ApplicationRecord
   belongs_to :label
 
   scope :inc_relations, -> { includes(:label, :user) }
+  scope :by_issue, ->(issue) { where(issue_id: issue.id) }
+  scope :by_merge_request, ->(merge_request) { where(merge_request_id: merge_request.id) }
 
   validates :label, presence: { unless: :importing? }, on: :create
+  validate :exactly_one_issuable
 
   after_save :expire_etag_cache
   after_destroy :expire_etag_cache
@@ -41,12 +41,6 @@ class ResourceLabelEvent < ApplicationRecord
     issue || merge_request
   end
 
-  def discussion_id(resource = nil)
-    strong_memoize(:discussion_id) do
-      Digest::SHA1.hexdigest(discussion_id_key.join("-"))
-    end
-  end
-
   def project
     issuable.project
   end
@@ -109,10 +103,6 @@ class ResourceLabelEvent < ApplicationRecord
   def resource_parent
     issuable.project || issuable.group
   end
-
-  def discussion_id_key
-    [self.class.name, created_at, user_id]
-  end
 end
 
 ResourceLabelEvent.prepend_if_ee('EE::ResourceLabelEvent')

app/models/resource_milestone_event.rb

 # frozen_string_literal: true
 
-class ResourceMilestoneEvent < ApplicationRecord
-  include Gitlab::Utils::StrongMemoize
-  include Importable
-  include ResourceEventTools
-
+class ResourceMilestoneEvent < ResourceEvent
   belongs_to :issue
   belongs_to :merge_request
   belongs_to :milestone
@@ -12,6 +8,8 @@ class ResourceMilestoneEvent < ApplicationRecord
   scope :by_issue, ->(issue) { where(issue_id: issue.id) }
   scope :by_merge_request, ->(merge_request) { where(merge_request_id: merge_request.id) }
 
+  validate :exactly_one_issuable
+
   enum action: {
          add: 1,
          remove: 2
@@ -23,8 +21,4 @@ class ResourceMilestoneEvent < ApplicationRecord
   def self.issuable_attrs
     %i(issue merge_request).freeze
   end
-
-  def resource
-    issue || merge_request
-  end
 end

app/models/resource_weight_event.rb

 # frozen_string_literal: true
 
-class ResourceWeightEvent < ApplicationRecord
-  include Gitlab::Utils::StrongMemoize
-
-  validates :user, presence: true
+class ResourceWeightEvent < ResourceEvent
   validates :issue, presence: true
 
-  belongs_to :user
   belongs_to :issue
 
   scope :by_issue, ->(issue) { where(issue_id: issue.id) }
-  scope :created_after, ->(time) { where('created_at > ?', time) }
-
-  def discussion_id(resource = nil)
-    strong_memoize(:discussion_id) do
-      Digest::SHA1.hexdigest(discussion_id_key.join("-"))
-    end
-  end
-
-  private
-
-  def discussion_id_key
-    [self.class.name, created_at, user_id]
-  end
 end

app/models/snippet.rb

@@ -301,6 +301,10 @@ class Snippet < ApplicationRecord
     repository.update!(shard_name: repository_storage, disk_path: disk_path)
   end
 
+  def can_cache_field?(field)
+    field != :content || MarkupHelper.gitlab_markdown?(file_name)
+  end
+
   class << self
     # Searches for snippets with a matching title or file name.
     #

app/models/user_bot_type_enums.rb

@@ -2,7 +2,7 @@
 
 module UserBotTypeEnums
   def self.bots
-    # When adding a new key, please ensure you are not conflicting with EE-only keys in app/models/user_bot_types_enums.rb
+    # When adding a new key, please ensure you are not conflicting with EE-only keys in app/models/user_bot_type_enums.rb
     {
       alert_bot: 2
     }

bin/mail_room

@@ -19,7 +19,7 @@ get_mail_room_pid()
 
 start()
 {
-  bin/daemon_with_pidfile $mail_room_pidfile bundle exec mail_room -q -c $mail_room_config >> $mail_room_logfile 2>&1
+  bin/daemon_with_pidfile $mail_room_pidfile bundle exec mail_room --log-exit-as json -q -c $mail_room_config >> $mail_room_logfile 2>&1
 }
 
 stop()

changelogs/unreleased/201771.yml

+---
+title: Replace content_viewer_spec setTimeouts with semantic actions / events
+merge_request:
+author: Oregand
+type: other

changelogs/unreleased/202639.yml

+---
+title: Replace line diff number css selector with actual HTML inside MRs
+merge_request:
+author: Oregand
+type: other

changelogs/unreleased/207126-more-descriptive-error-messages-in-migration-helpers.yml

+---
+title: Improve error messages of failed migrations
+merge_request: 25457
+author:
+type: changed

changelogs/unreleased/207976-stop-markdown-caching-of-non-markdown-snippet-content.yml

+---
+title: Fix Snippet content incorrectly caching
+merge_request: 25985
+author:
+type: fixed

changelogs/unreleased/34086-es-bulk-incremental-index-updates.yml

+---
+title: 'Add a bulk processor for elasticsearch incremental updates'
+merge_request: 24298
+author:
+type: added

changelogs/unreleased/fix-dependency-proxy-link.yml

+---
+title: Add link to dependency proxy docs on the dependency proxy page
+merge_request: 26092
+author:
+type: changed

changelogs/unreleased/georgekoltsov-fix-epic-issues.yml

+---
+title: Fix issues missing on epic's page after project import
+merge_request: 26099
+author:
+type: fixed

changelogs/unreleased/kassio-fix-dev-seed.yml

+---
+title: Fix dev vulnerabilities seeder
+merge_request: 26169
+author:
+type: fixed

changelogs/unreleased/mk-hide-secondary-only-setting.yml

+---
+title: 'Geo: Show secondary-only setting on only on secondaries'
+merge_request: 26029
+author:
+type: fixed

changelogs/unreleased/sh-cache-ci-variables.yml

+---
+title: Memoize loading of CI variables
+merge_request: 26147
+author:
+type: performance

changelogs/unreleased/sh-disable-line-in-marginalia.yml

+---
+title: Disable Marginalia line backtrace in production
+merge_request: 26199
+author:
+type: performance

config/gitlab.yml.example

@@ -454,6 +454,11 @@ production: &base
     pseudonymizer_worker:
       cron: "0 * * * *"
 
+    # Elasticsearch bulk updater for incremental updates.
+    # NOTE: This will only take effect if elasticsearch is enabled.
+    elastic_index_bulk_cron_worker:
+      cron: "*/1 * * * *"
+
   registry:
     # enabled: true
     # host: registry.example.com

config/initializers/0_marginalia.rb

@@ -9,7 +9,13 @@ require 'marginalia'
 # Refer: https://github.com/basecamp/marginalia/blob/v1.8.0/lib/marginalia/railtie.rb#L67
 ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.prepend(Gitlab::Marginalia::ActiveRecordInstrumentation)
 
-Marginalia::Comment.components = [:application, :controller, :action, :correlation_id, :jid, :job_class, :line]
+Marginalia::Comment.components = [:application, :controller, :action, :correlation_id, :jid, :job_class]
+
+# As mentioned in https://github.com/basecamp/marginalia/pull/93/files,
+# adding :line has some overhead because a regexp on the backtrace has
+# to be run on every SQL query. Only enable this in development because
+# we've seen it slow things down.
+Marginalia::Comment.components << :line if Rails.env.development?
 
 Gitlab::Marginalia.set_application_name
 

config/initializers/1_settings.rb

@@ -537,6 +537,9 @@ Gitlab.ee do
   Settings.cron_jobs['update_max_seats_used_for_gitlab_com_subscriptions_worker'] ||= Settingslogic.new({})
   Settings.cron_jobs['update_max_seats_used_for_gitlab_com_subscriptions_worker']['cron'] ||= '0 12 * * *'
   Settings.cron_jobs['update_max_seats_used_for_gitlab_com_subscriptions_worker']['job_class'] = 'UpdateMaxSeatsUsedForGitlabComSubscriptionsWorker'
+  Settings.cron_jobs['elastic_index_bulk_cron_worker'] ||= Settingslogic.new({})
+  Settings.cron_jobs['elastic_index_bulk_cron_worker']['cron'] ||= '*/1 * * * *'
+  Settings.cron_jobs['elastic_index_bulk_cron_worker']['job_class'] ||= 'ElasticIndexBulkCronWorker'
 end
 
 #

config/routes.rb

@@ -121,10 +121,7 @@ Rails.application.routes.draw do
       draw :country
       draw :country_state
       draw :subscription
-
-      constraints(-> (*) { Gitlab::Analytics.any_features_enabled? }) do
-        draw :analytics
-      end
+      draw :analytics
     end
 
     if ENV['GITLAB_CHAOS_SECRET'] || Rails.env.development? || Rails.env.test?

doc/administration/auth/oidc.md

@@ -42,6 +42,7 @@ The OpenID Connect will provide you with a client details and secret for you to
          'discovery' => true,
          'client_auth_method' => 'query',
          'uid_field' => '<uid_field>',
+         'send_scope_to_token_endpoint' => 'false',
          'client_options' => {
            'identifier' => '<your_oidc_client_id>',
            'secret' => '<your_oidc_client_secret>',
@@ -65,6 +66,7 @@ The OpenID Connect will provide you with a client details and secret for you to
            discovery: true,
            client_auth_method: 'query',
            uid_field: '<uid_field>',
+           send_scope_to_token_endpoint: false,
            client_options: {
              identifier: '<your_oidc_client_id>',
              secret: '<your_oidc_client_secret>',
@@ -92,6 +94,8 @@ The OpenID Connect will provide you with a client details and secret for you to
      - If not specified, defaults to `basic`.
    - `<uid_field>` (optional) is the field name from the `user_info` details that will be used as `uid` value. For example, `preferred_username`.
      If this value is not provided or the field with the configured value is missing from the `user_info` details, the `uid` will use the `sub` field.
+   - `send_scope_to_token_endpoint` is `true` by default. In other words, the `scope` parameter is normally included in requests to the token endpoint.
+     However, if your OpenID Connect provider does not accept the `scope` parameter in such requests, set this to `false`.
    - `client_options` are the OpenID Connect client-specific options. Specifically:
      - `identifier` is the client identifier as configured in the OpenID Connect service provider.
      - `secret` is the client secret as configured in the OpenID Connect service provider.

doc/administration/auth/okta.md

@@ -42,21 +42,6 @@ Now that the Okta app is configured, it's time to enable it in GitLab.
 
 ## Configure GitLab
 
-1. On your GitLab server, open the configuration file:
-
-   **For Omnibus GitLab installations**
-
-   ```shell
-   sudo editor /etc/gitlab/gitlab.rb
-   ```
-
-   **For installations from source**
-
-   ```shell
-   cd /home/git/gitlab
-   sudo -u git -H editor config/gitlab.yml
-   ```
-
 1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration)
    for initial settings.
 
@@ -66,13 +51,19 @@ Now that the Okta app is configured, it's time to enable it in GitLab.
 
    **For Omnibus GitLab installations**
 
+   Edit `/etc/gitlab/gitlab.rb`:
+
    ```ruby
    gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
    gitlab_rails['omniauth_block_auto_created_users'] = false
    ```
 
+   ---
+
    **For installations from source**
 
+   Edit `config/gitlab.yml`:
+
    ```yaml
    allow_single_sign_on: ["saml"]
    block_auto_created_users: false
@@ -83,15 +74,21 @@ Now that the Okta app is configured, it's time to enable it in GitLab.
 
    **For Omnibus GitLab installations**
 
+   Edit `/etc/gitlab/gitlab.rb`:
+
    ```ruby
    gitlab_rails['omniauth_auto_link_saml_user'] = true
    ```
 
+   ---
+
    **For installations from source**
 
-   ```yaml
-   auto_link_saml_user: true
-   ```
+   Edit `config/gitlab.yml`:
+
+    ```yaml
+    auto_link_saml_user: true
+    ```
 
 1. Add the provider configuration.
 

doc/administration/gitaly/index.md

@@ -6,9 +6,9 @@ components can read or write Git data. GitLab components that access Git
 repositories (GitLab Rails, GitLab Shell, GitLab Workhorse, etc.) act as clients
 to Gitaly. End users do not have direct access to Gitaly.
 
-In the rest of this page, Gitaly server is referred to the standalone node that
-only runs Gitaly, and Gitaly client to the GitLab Rails node that runs all other
-processes except Gitaly.
+On this page, *Gitaly server* refers to a standalone node that only runs Gitaly
+and *Gitaly client* is a GitLab Rails app node that runs all other processes
+except Gitaly.
 
 ## Architecture
 
@@ -20,7 +20,7 @@ Here's a high-level architecture overview of how Gitaly is used.
 
 The Gitaly service itself is configured via a [TOML configuration file](reference.md).
 
-In case you want to change some of its settings:
+If you want to change any of its settings:
 
 **For Omnibus GitLab**
 
@@ -54,10 +54,6 @@ scenario, the [new repository indexer](../../integration/elasticsearch.md#elasti
 needs to be enabled in your GitLab configuration. [Since GitLab v12.3](https://gitlab.com/gitlab-org/gitlab/issues/6481),
 the new indexer becomes the default and no configuration is required.
 
-NOTE: **Note:** While Gitaly can be used as a replacement for NFS, it's not recommended
-to use EFS as it may impact GitLab's performance. Review the [relevant documentation](../high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs)
-for more details.
-
 ### Network architecture
 
 The following list depicts what the network architecture of Gitaly is:
@@ -568,30 +564,6 @@ server with the following settings.
 
 1. Save the file and [restart GitLab](../restart_gitlab.md#installations-from-source).
 
-## Eliminating NFS altogether
-
-If you are planning to use Gitaly without NFS for your storage needs
-and want to eliminate NFS from your environment altogether, there are
-a few things that you need to do:
-
-1. Make sure the [`git` user home directory](https://docs.gitlab.com/omnibus/settings/configuration.html#moving-the-home-directory-for-a-user) is on local disk.
-1. Configure [database lookup of SSH keys](../operations/fast_ssh_key_lookup.md)
-   to eliminate the need for a shared `authorized_keys` file.
-1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage)
-   including [incremental logging](../job_logs.md#new-incremental-logging-architecture).
-1. Configure [object storage for LFS objects](../lfs/lfs_administration.md#storing-lfs-objects-in-remote-object-storage).
-1. Configure [object storage for uploads](../uploads.md#using-object-storage-core-only).
-1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage).
-1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature).
-1. Configure [object storage for dependency proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature).
-1. Configure [object storage for Mattermost](https://docs.mattermost.com/administration/config-settings.html#file-storage) (optional feature).
-
-NOTE: **Note:**
-One current feature of GitLab that still requires a shared directory (NFS) is
-[GitLab Pages](../../user/project/pages/index.md).
-There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/issues/196)
-to eliminate the need for NFS to support GitLab Pages.
-
 ## Limiting RPC concurrency
 
 It can happen that CI clone traffic puts a large strain on your Gitaly

doc/administration/high_availability/database.md

@@ -22,11 +22,9 @@ If you use a cloud-managed service, or provide your own PostgreSQL:
 1. Configure the GitLab application servers with the appropriate details.
    This step is covered in [Configuring GitLab for HA](gitlab.md).
 
-## PostgreSQL in a Scaled Environment
+## PostgreSQL in a Scaled and Highly Available Environment
 
-This section is relevant for [Scaled Architecture](README.md#scalable-architecture-examples)
-environments including [Basic Scaling](README.md#basic-scaling) and
-[Full Scaling](README.md#full-scaling).
+This section is relevant for [Scalable and Highly Available Setups](README.md).
 
 ### Provide your own PostgreSQL instance **(CORE ONLY)**
 
@@ -94,23 +92,6 @@ deploy the bundled PostgreSQL.
 Advanced configuration options are supported and can be added if
 needed.
 
-Continue configuration of other components by going
-[back to Scaled Architectures](README.md#scalable-architecture-examples)
-
-## PostgreSQL with High Availability
-
-This section is relevant for [High Availability Architecture](README.md#high-availability-architecture-examples)
-environments including [Horizontal](README.md#horizontal),
-[Hybrid](README.md#hybrid), and
-[Fully Distributed](README.md#fully-distributed).
-
-### Provide your own PostgreSQL instance **(CORE ONLY)**
-
-If you want to use your own deployed PostgreSQL instance(s),
-see [Provide your own PostgreSQL instance](#provide-your-own-postgresql-instance-core-only)
-for more details. However, you can use the GitLab Omnibus package to easily
-deploy the bundled PostgreSQL.
-
 ### High Availability with GitLab Omnibus **(PREMIUM ONLY)**
 
 > Important notes:

doc/administration/high_availability/gitaly.md

@@ -11,18 +11,15 @@ should consider using Gitaly on a separate node.
 See the [Gitaly HA Epic](https://gitlab.com/groups/gitlab-org/-/epics/289) to
 track plans and progress toward high availability support.
 
-This document is relevant for [Scaled Architecture](README.md#scalable-architecture-examples)
-environments and [High Availability Architecture](README.md#high-availability-architecture-examples).
+This document is relevant for [Scalable and Highly Available Setups](README.md).
 
 ## Running Gitaly on its own server
 
 See [Running Gitaly on its own server](../gitaly/index.md#running-gitaly-on-its-own-server)
 in Gitaly documentation.
 
-Continue configuration of other components by going back to:
-
-- [Scaled Architectures](README.md#scalable-architecture-examples)
-- [High Availability Architectures](README.md#high-availability-architecture-examples)
+Continue configuration of other components by going back to the
+[Scaling and High Availability](README.md#gitlab-components-and-configuration-instructions) page.
 
 ## Enable Monitoring
 

doc/administration/high_availability/object_storage.md

+---
+type: reference
+---
+
+# Cloud Object Storage
+
+GitLab supports utilizing a Cloud Object Storage service over [NFS](nfs.md) for holding
+numerous types of data. This is recommended in larger setups as object storage is
+typically much more performant and reliable.
+
+For configuring GitLab to use Object Storage refer to the following guides:
+
+1. Make sure the [`git` user home directory](https://docs.gitlab.com/omnibus/settings/configuration.html#moving-the-home-directory-for-a-user) is on local disk.
+1. Configure [database lookup of SSH keys](../operations/fast_ssh_key_lookup.md)
+   to eliminate the need for a shared `authorized_keys` file.
+1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage)
+   including [incremental logging](../job_logs.md#new-incremental-logging-architecture).
+1. Configure [object storage for LFS objects](../lfs/lfs_administration.md#storing-lfs-objects-in-remote-object-storage).
+1. Configure [object storage for uploads](../uploads.md#using-object-storage-core-only).
+1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage).
+1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature).
+1. Configure [object storage for dependency proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature).
+
+NOTE: **Note:**
+One current feature of GitLab that still requires a shared directory (NFS) is
+[GitLab Pages](../../user/project/pages/index.md).
+There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/issues/196)
+to eliminate the need for NFS to support GitLab Pages.

doc/administration/high_availability/redis.md

@@ -20,11 +20,9 @@ The following are the requirements for providing your own Redis instance:
 Note the Redis node's IP address or hostname, port, and password (if required).
 These will be necessary when configuring the GitLab application servers later.
 
-## Redis in a Scaled Environment
+## Redis in a Scaled and Highly Available Environment
 
-This section is relevant for [Scaled Architecture](README.md#scalable-architecture-examples)
-environments including [Basic Scaling](README.md#basic-scaling) and
-[Full Scaling](README.md#full-scaling).
+This section is relevant for [Scalable and Highly Available Setups](README.md).
 
 ### Provide your own Redis instance **(CORE ONLY)**
 
@@ -85,22 +83,8 @@ Omnibus:
 Advanced configuration options are supported and can be added if
 needed.
 
-Continue configuration of other components by going
-[back to Scaled Architectures](README.md#scalable-architecture-examples)
-
-## Redis with High Availability
-
-This section is relevant for [High Availability Architecture](README.md#high-availability-architecture-examples)
-environments including [Horizontal](README.md#horizontal),
-[Hybrid](README.md#hybrid), and
-[Fully Distributed](README.md#fully-distributed).
-
-### Provide your own Redis instance **(CORE ONLY)**
-
-If you want to use your own deployed Redis instance(s),
-see [Provide your own Redis instance](#provide-your-own-redis-instance-core-only)
-for more details. However, you can use the GitLab Omnibus package to easily
-deploy the bundled Redis.
+Continue configuration of other components by going back to the
+[Scaling and High Availability](README.md#gitlab-components-and-configuration-instructions) page.
 
 ### High Availability with GitLab Omnibus **(PREMIUM ONLY)**
 

doc/api/README.md

@@ -355,7 +355,7 @@ curl --head --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example
 
 The response will then be:
 
-```
+```http
 HTTP/1.1 200 OK
 Cache-Control: no-cache
 Content-Length: 1103
@@ -415,7 +415,7 @@ curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab
 
 The response header includes a link to the next page. For example:
 
-```
+```http
 HTTP/1.1 200 OK
 ...
 Link: <https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc&id_after=42>; rel="next"
@@ -540,7 +540,7 @@ Such errors appear in two cases:
 
 When an attribute is missing, you will get something like:
 
-```
+```http
 HTTP/1.1 400 Bad Request
 Content-Type: application/json
 {
@@ -551,7 +551,7 @@ Content-Type: application/json
 When a validation error occurs, error messages will be different. They will
 hold all details of validation errors:
 
-```
+```http
 HTTP/1.1 400 Bad Request
 Content-Type: application/json
 {
@@ -589,7 +589,7 @@ follows:
 
 When you try to access an API URL that does not exist you will receive 404 Not Found.
 
-```
+```http
 HTTP/1.1 404 Not Found
 Content-Type: application/json
 {

doc/api/pipeline_triggers.md

@@ -6,7 +6,7 @@ You can read more about [triggering pipelines through the API](../ci/triggers/RE
 
 Get a list of project's build triggers.
 
-```
+```plaintext
 GET /projects/:id/triggers
 ```
 
@@ -14,7 +14,7 @@ GET /projects/:id/triggers
 |-----------|---------|----------|---------------------|
 | `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
 
-```
+```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
 ```
 
@@ -36,7 +36,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
 
 Get details of project's build trigger.
 
-```
+```plaintext
 GET /projects/:id/triggers/:trigger_id
 ```
 
@@ -45,7 +45,7 @@ GET /projects/:id/triggers/:trigger_id
 | `id`         | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
 | `trigger_id` | integer | yes      | The trigger id           |
 
-```
+```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5"
 ```
 
@@ -65,7 +65,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
 
 Create a trigger for a project.
 
-```
+```plaintext
 POST /projects/:id/triggers
 ```
 
@@ -74,7 +74,7 @@ POST /projects/:id/triggers
 | `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
 | `description` | string  | yes      | The trigger name         |
 
-```
+```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers"
 ```
 
@@ -94,7 +94,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form descrip
 
 Update a trigger for a project.
 
-```
+```plaintext
 PUT /projects/:id/triggers/:trigger_id
 ```
 
@@ -104,7 +104,7 @@ PUT /projects/:id/triggers/:trigger_id
 | `trigger_id`  | integer | yes      | The trigger id           |
 | `description` | string  | no       | The trigger name         |
 
-```
+```shell
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers/10"
 ```
 
@@ -124,7 +124,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form descript
 
 Remove a project's build trigger.
 
-```
+```plaintext
 DELETE /projects/:id/triggers/:trigger_id
 ```
 
@@ -133,6 +133,6 @@ DELETE /projects/:id/triggers/:trigger_id
 | `id`           | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user      |
 | `trigger_id`   | integer | yes      | The trigger id           |
 
-```
+```shell
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5"
 ```

doc/api/releases/links.md

@@ -9,7 +9,7 @@ GitLab supports links links to `http`, `https`, and `ftp` assets.
 
 Get assets as links from a Release.
 
-```
+```plaintext
 GET /projects/:id/releases/:tag_name/assets/links
 ```
 
@@ -47,7 +47,7 @@ Example response:
 
 Get an asset as a link from a Release.
 
-```
+```plaintext
 GET /projects/:id/releases/:tag_name/assets/links/:link_id
 ```
 
@@ -78,7 +78,7 @@ Example response:
 
 Create an asset as a link from a Release.
 
-```
+```plaintext
 POST /projects/:id/releases/:tag_name/assets/links
 ```
 
@@ -114,7 +114,7 @@ Example response:
 
 Update an asset as a link from a Release.
 
-```
+```plaintext
 PUT /projects/:id/releases/:tag_name/assets/links/:link_id
 ```
 
@@ -150,7 +150,7 @@ Example response:
 
 Delete an asset as a link from a Release.
 
-```
+```plaintext
 DELETE /projects/:id/releases/:tag_name/assets/links/:link_id
 ```
 

doc/api/scim.md

@@ -122,7 +122,7 @@ Parameters:
 | `userName`   | string      | yes | Username of the user. |
 | `emails`     | JSON string | yes | Work email. |
 | `name`       | JSON string | yes | Name of the user. |
-| `meta`       | string      | no  | Resource type (`User'). |
+| `meta`       | string      | no  | Resource type (`User`). |
 
 Example request:
 

doc/api/search.md

@@ -751,7 +751,7 @@ Search within the specified project.
 
 If a user is not a member of a project and the project is private, a `GET` request on that project will result to a `404` status code.
 
-```
+```plaintext
 GET /projects/:id/search
 ```
 

doc/api/services.md

@@ -1145,7 +1145,7 @@ Parameters:
 | `merge_requests_events` | boolean | false | Enable notifications for merge request events |
 | `tag_push_events` | boolean | false | Enable notifications for tag push events |
 | `note_events` | boolean | false | Enable notifications for note events |
-| `confidental_note_events` | boolean | false | Enable notifications for confidential note events |
+| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
 | `pipeline_events` | boolean | false | Enable notifications for pipeline events |
 | `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
 

doc/api/settings.md

@@ -10,7 +10,7 @@ administrator in order to perform this action.
 List the current [application settings](#list-of-settings-that-can-be-accessed-via-api-calls)
 of the GitLab instance.
 
-```
+```plaintext
 GET /application/settings
 ```
 
@@ -90,7 +90,7 @@ the `file_template_project_id`, `deletion_adjourned_period`, or the `geo_node_al
 Use an API call to modify GitLab instance
 [application settings](#list-of-settings-that-can-be-accessed-via-api-calls).
 
-```
+```plaintext
 PUT /application/settings
 ```
 

doc/api/sidekiq_metrics.md

@@ -10,7 +10,7 @@ of Sidekiq, its jobs, queues, and processes.
 List information about all the registered queues, their backlog and their
 latency.
 
-```
+```plaintext
 GET /sidekiq/queue_metrics
 ```
 
@@ -35,7 +35,7 @@ Example response:
 
 List information about all the Sidekiq workers registered to process your queues.
 
-```
+```plaintext
 GET /sidekiq/process_metrics
 ```
 
@@ -77,7 +77,7 @@ Example response:
 
 List information about the jobs that Sidekiq has performed.
 
-```
+```plaintext
 GET /sidekiq/job_stats
 ```
 
@@ -102,7 +102,7 @@ Example response:
 
 List all the currently available information about Sidekiq.
 
-```
+```plaintext
 GET /sidekiq/compound_metrics
 ```
 

doc/api/statistics.md

@@ -8,7 +8,7 @@ administrator in order to perform this action.
 NOTE: **Note:**
 These statistics are approximate.
 
-```
+```plaintext
 GET /application/statistics
 ```
 

doc/api/suggestions.md

@@ -7,7 +7,7 @@ Every API call to suggestions must be authenticated.
 Applies a suggested patch in a merge request. Users must be
 at least [Developer](../user/permissions.md) to perform such action.
 
-```
+```plaintext
 PUT /suggestions/:id/apply
 ```
 

doc/api/system_hooks.md

@@ -11,7 +11,7 @@ Read more about [system hooks](../system_hooks/system_hooks.md).
 
 Get a list of all system hooks.
 
-```
+```plaintext
 GET /hooks
 ```
 
@@ -42,7 +42,7 @@ Example response:
 
 Add a new system hook.
 
-```
+```plaintext
 POST /hooks
 ```
 
@@ -81,7 +81,7 @@ Example response:
 
 ## Test system hook
 
-```
+```plaintext
 GET /hooks/:id
 ```
 
@@ -112,7 +112,7 @@ Example response:
 
 Deletes a system hook.
 
-```
+```plaintext
 DELETE /hooks/:id
 ```
 

doc/api/tags.md

@@ -6,7 +6,7 @@ Get a list of repository tags from a project, sorted by name in reverse
 alphabetical order. This endpoint can be accessed without authentication if the
 repository is publicly accessible.
 
-```
+```plaintext
 GET /projects/:id/repository/tags
 ```
 
@@ -57,7 +57,7 @@ Parameters:
 Get a specific repository tag determined by its name. This endpoint can be
 accessed without authentication if the repository is publicly accessible.
 
-```
+```plaintext
 GET /projects/:id/repository/tags/:tag_name
 ```
 
@@ -104,7 +104,7 @@ Example Response:
 
 Creates a new tag in the repository that points to the supplied ref.
 
-```
+```plaintext
 POST /projects/:id/repository/tags
 ```
 
@@ -164,7 +164,7 @@ status code `405` with an explaining error message is returned.
 
 Deletes a tag of a repository with given name.
 
-```
+```plaintext
 DELETE /projects/:id/repository/tags/:tag_name
 ```
 
@@ -178,7 +178,7 @@ Parameters:
 Add release notes to the existing Git tag. If there
 already exists a release for the given tag, status code `409` is returned.
 
-```
+```plaintext
 POST /projects/:id/repository/tags/:tag_name/release
 ```
 
@@ -210,7 +210,7 @@ Response:
 
 Updates the release notes of a given release.
 
-```
+```plaintext
 PUT /projects/:id/repository/tags/:tag_name/release
 ```
 

doc/api/templates/dockerfiles.md

@@ -12,7 +12,7 @@ information on Dockerfiles, see the
 
 Get all Dockerfile templates.
 
-```
+```plaintext
 GET /templates/dockerfiles
 ```
 
@@ -99,7 +99,7 @@ Example response:
 
 Get a single Dockerfile template.
 
-```
+```plaintext
 GET /templates/dockerfiles/:key
 ```
 

doc/api/templates/licenses.md

@@ -13,7 +13,7 @@ resources available online.
 
 Get all license templates.
 
-```
+```plaintext
 GET /templates/licenses
 ```
 
@@ -110,7 +110,7 @@ Example response:
 Get a single license template. You can pass parameters to replace the license
 placeholder.
 
-```
+```plaintext
 GET /templates/licenses/:key
 ```
 

doc/api/todos.md

@@ -7,7 +7,7 @@
 Returns a list of todos. When no filter is applied, it returns all pending todos
 for the current user. Different filters allow the user to precise the request.
 
-```
+```plaintext
 GET /todos
 ```
 
@@ -184,7 +184,7 @@ Example Response:
 Marks a single pending todo given by its ID for the current user as done. The
 todo marked as done is returned in the response.
 
-```
+```plaintext
 POST /todos/:id/mark_as_done
 ```
 
@@ -280,7 +280,7 @@ Example Response:
 
 Marks all pending todos for the current user as done. It returns the HTTP status code `204` with an empty response.
 
-```
+```plaintext
 POST /todos/mark_as_done
 ```
 

doc/api/version.md

@@ -5,7 +5,7 @@
 Retrieve version information for this GitLab instance. Responds `200 OK` for
 authenticated users.
 
-```
+```plaintext
 GET /version
 ```
 

doc/api/visual_review_discussions.md

@@ -10,7 +10,7 @@ feedback from [Visual Reviews](../ci/review_apps/index.md#visual-reviews-starter
 Creates a new thread to a single project merge request. This is similar to creating
 a note but other comments (replies) can be added to it later.
 
-```
+```plaintext
 POST /projects/:id/merge_requests/:merge_request_iid/visual_review_discussions
 ```
 

doc/api/vulnerability_findings.md

@@ -34,7 +34,7 @@ Read more on [pagination](README.md#pagination).
 
 List all of a project's vulnerability findings.
 
-```
+```plaintext
 GET /projects/:id/vulnerability_findings
 GET /projects/:id/vulnerability_findings?report_type=sast
 GET /projects/:id/vulnerability_findings?report_type=container_scanning

doc/api/wikis.md

@@ -8,7 +8,7 @@ Available only in APIv4.
 
 Get all wiki pages for a given project.
 
-```
+```plaintext
 GET /projects/:id/wikis
 ```
 
@@ -49,7 +49,7 @@ Example response:
 
 Get a wiki page for a given project.
 
-```
+```plaintext
 GET /projects/:id/wikis/:slug
 ```
 
@@ -77,7 +77,7 @@ Example response:
 
 Creates a new wiki page for the given repository with the given title, slug, and content.
 
-```
+```plaintext
 POST /projects/:id/wikis
 ```
 
@@ -107,7 +107,7 @@ Example response:
 
 Updates an existing wiki page. At least one parameter is required to update the wiki page.
 
-```
+```plaintext
 PUT /projects/:id/wikis/:slug
 ```
 
@@ -138,7 +138,7 @@ Example response:
 
 Deletes a wiki page with a given slug.
 
-```
+```plaintext
 DELETE /projects/:id/wikis/:slug
 ```
 
@@ -160,7 +160,7 @@ On success the HTTP status code is `204` and no JSON response is expected.
 Uploads a file to the attachment folder inside the wiki's repository. The
  attachment folder is the `uploads` folder.
 
-```
+```plaintext
 POST /projects/:id/wikis/attachments
 ```
 

doc/ci/caching/index.md

@@ -206,10 +206,11 @@ templates](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/lib/gitlab/ci/t
 
 ### Caching Node.js dependencies
 
-Assuming your project is using [npm](https://www.npmjs.com/) or
-[Yarn](https://classic.yarnpkg.com/en/) to install the Node.js dependencies, the
-following example defines `cache` globally so that all jobs inherit it.
-Node.js modules are installed in `node_modules/` and are cached per-branch:
+Assuming your project is using [npm](https://www.npmjs.com/) to install the Node.js
+dependencies, the following example defines `cache` globally so that all jobs inherit it.
+By default, npm stores cache data in the home folder `~/.npm` but since
+[you can't cache things outside of the project directory](../yaml/README.md#cachepaths),
+we tell npm to use `./.npm` instead, and it is cached per-branch:
 
 ```yaml
 #
@@ -221,10 +222,10 @@ image: node:latest
 cache:
   key: ${CI_COMMIT_REF_SLUG}
   paths:
-  - node_modules/
+  - .npm/
 
 before_script:
-  - npm install
+  - npm ci --cache .npm --prefer-offline
 
 test_async:
   script:

doc/ci/variables/README.md

@@ -571,9 +571,12 @@ Below you can find supported syntax reference:
    - `$VARIABLE =~ /^content.*/`
    - `$VARIABLE_1 !~ /^content.*/` (introduced in GitLab 11.11)
 
-   It is possible perform pattern matching against a variable and regular
-   expression. Expression like this evaluates to truth if matches are found
-   when using `=~`. It evaluates to truth if matches are not found when `!~` is used.
+   Variable pattern matching with regular expressions uses the
+   [RE2 regular expression syntax](https://github.com/google/re2/wiki/Syntax).
+   Expressions evaluate as `true` if:
+
+   - Matches are found when using `=~`.
+   - Matches are *not* found when using `!~`.
 
    Pattern matching is case-sensitive by default. Use `i` flag modifier, like
    `/pattern/i` to make a pattern case-insensitive.

doc/ci/yaml/README.md

@@ -857,7 +857,10 @@ In this example, if the first rule:
 
 `rules:if` differs slightly from `only:variables` by accepting only a single
 expression string, rather than an array of them. Any set of expressions to be
-evaluated should be conjoined into a single expression using `&&` or `||`. For example:
+evaluated should be conjoined into a single expression using `&&` or `||`, and use
+the [variable matching syntax](../variables/README.md#supported-syntax).
+
+For example:
 
 ```yaml
 job:

doc/development/README.md

@@ -9,8 +9,20 @@ description: 'Learn how to contribute to GitLab.'
 
 - Set up GitLab's development environment with [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/README.md)
 - [GitLab contributing guide](contributing/index.md)
-  - [Issues workflow](contributing/issue_workflow.md) (issue tracker guidelines, triaging, labels, feature proposals, issue weight, regression issues, technical and UX debt)
-  - [Merge requests workflow](contributing/merge_request_workflow.md) (merge request guidelines, contribution acceptance criteria, definition of done, dependencies)
+  - [Issues workflow](contributing/issue_workflow.md). For information on:
+    - Issue tracker guidelines.
+    - Triaging.
+    - Labels.
+    - Feature proposals.
+    - Issue weight.
+    - Regression issues.
+    - Technical or UX debt.
+  - [Merge requests workflow](contributing/merge_request_workflow.md). For
+    information on:
+    - Merge request guidelines.
+    - Contribution acceptance criteria.
+    - Definition of done.
+    - Dependencies.
   - [Style guides](contributing/style_guides.md)
   - [Implement design & UI elements](contributing/design.md)
 - [GitLab Architecture Overview](architecture.md)

doc/development/architecture.md

@@ -288,7 +288,7 @@ GitLab CI is the open-source continuous integration service included with GitLab
 - Configuration: [Omnibus][grafana-omnibus], [Charts][grafana-charts]
 - Layer: Monitoring
 
-Grafana is an open source, feature rich metrics dashboard and graph editor for Graphite, Elasticsearch, OpenTSDB, Prometheus and InfluxDB.
+Grafana is an open source, feature rich metrics dashboard and graph editor for Graphite, Elasticsearch, OpenTSDB, Prometheus, and InfluxDB.
 
 #### Jaeger
 
@@ -321,7 +321,7 @@ Mattermost is an open source, private cloud, Slack-alternative from <https://mat
 - Configuration: [Omnibus][minio-omnibus], [Charts][minio-charts], [GDK][minio-gdk]
 - Layer: Core Service (Data)
 
-MinIO is an object storage server released under Apache License v2.0. It is compatible with Amazon S3 cloud storage service. It is best suited for storing unstructured data such as photos, videos, log files, backups and container / VM images. Size of an object can range from a few KBs to a maximum of 5TB.
+MinIO is an object storage server released under Apache License v2.0. It is compatible with Amazon S3 cloud storage service. It is best suited for storing unstructured data such as photos, videos, log files, backups, and container / VM images. Size of an object can range from a few KBs to a maximum of 5TB.
 
 #### NGINX
 

doc/development/code_review.md

@@ -17,7 +17,7 @@ uncovered edge cases. The reviewer can be from a different team, but it is
 recommended to pick someone who knows the domain well. You can read more about the
 importance of involving reviewer(s) in the section on the responsibility of the author below.
 
-If you need some guidance (e.g. it's your first merge request), feel free to ask
+If you need some guidance (for example, it's your first merge request), feel free to ask
 one of the [Merge request coaches](https://about.gitlab.com/company/team/).
 
 If you need assistance with security scans or comments, feel free to include the
@@ -148,7 +148,7 @@ architecture, code organization, separation of concerns, tests, DRYness,
 consistency, and readability.
 
 Since a maintainer's job only depends on their knowledge of the overall GitLab
-codebase, and not that of any specific domain, they can review, approve and merge
+codebase, and not that of any specific domain, they can review, approve, and merge
 merge requests from any team and in any product area.
 
 In fact, authors are encouraged to get their merge requests merged by maintainers
@@ -334,7 +334,7 @@ reviewee.
   reviewer before doing it, but have the courage to do it when you believe it is
   important.
 - In the interest of [Iteration](https://about.gitlab.com/handbook/values/#iteration),
-  if, as a reviewer, your suggestions are non-blocking changes or personal preference
+  if your review suggestions are non-blocking changes, or personal preference
   (not a documented or agreed requirement), consider approving the merge request
   before passing it back to the author. This allows them to implement your suggestions
   if they agree, or allows them to pass it onto the

doc/development/contributing/design.md

@@ -9,7 +9,11 @@ To better understand the priority by which UX tackles issues, see the [UX sectio
 
 Once an issue has been worked on and is ready for development, a UXer removes the ~"UX" label and applies the ~"UX ready" label to that issue.
 
-There is a special type label called ~"product discovery". It represents a discovery issue intended for UX, PM, FE, and BE to discuss the problem and potential solutions. The final output for this issue could be a doc of requirements, a design artifact, or even a prototype. The solution will be developed in a subsequent milestone.
+There is a special type label called ~"product discovery" intended for UX,
+PM, FE, and BE. It represents a discovery issue to discuss the problem and
+potential solutions. The final output for this issue could be a doc of
+requirements, a design artifact, or even a prototype. The solution will be
+developed in a subsequent milestone.
 
 ~"product discovery" issues are like any other issue and should contain a milestone label, ~"Deliverable" or ~"Stretch", when scheduled in the current milestone.
 
@@ -17,7 +21,7 @@ The initial issue should be about the problem we are solving. If a separate [pro
 is needed for additional research and design work, it will be created by a PM or UX person.
 Assign the ~UX, ~"product discovery" and ~"Deliverable" labels, add a milestone and
 use a title that makes it clear that the scheduled issue is product discovery
-(e.g. `Product discovery for XYZ`).
+(for example, `Product discovery for XYZ`).
 
 In order to complete a product discovery issue in a release, you must complete the following:
 

doc/development/database_review.md

@@ -12,7 +12,7 @@ A database review is required for:
   including files in:
   - `db/`
   - `lib/gitlab/background_migration/`
-- Changes to the database tooling, e.g.:
+- Changes to the database tooling. For example:
   - migration or ActiveRecord helpers in `lib/gitlab/database/`
   - load balancing
 - Changes that produce SQL queries that are beyond the obvious. It is
@@ -50,7 +50,7 @@ A database **reviewer**'s role is to:
 Currently we have a [critical shortage of database maintainers](https://gitlab.com/gitlab-org/gitlab/issues/29717). Until we are able to increase the number of database maintainers to support the volume of reviews, we have implemented this temporary solution. If the database **reviewer** cannot find an available database **maintainer** then:
 
 1. Assign the MR for a second review by a **database trainee maintainer** for further review.
-1. Once satisfied with the review process, and if the database **maintainer** is still not available, skip the database maintainer approval step and assign the merge request to a backend maintainer for final review and approval.
+1. Once satisfied with the review process and if the database **maintainer** is still not available, skip the database maintainer approval step and assign the merge request to a backend maintainer for final review and approval.
 
 A database **maintainer**'s role is to:
 
@@ -119,10 +119,10 @@ the following preparations into account.
 - Add foreign keys to any columns pointing to data in other tables, including [an index](migration_style_guide.md#adding-foreign-key-constraints).
 - Add indexes for fields that are used in statements such as `WHERE`, `ORDER BY`, `GROUP BY`, and `JOIN`s.
 
-#### Preparation when removing columns, tables, indexes or other structures
+#### Preparation when removing columns, tables, indexes, or other structures
 
 - Follow the [guidelines on dropping columns](what_requires_downtime.md#dropping-columns).
-- Generally it's best practice, but not a hard rule, to remove indexes and foreign keys in a post-deployment migration.
+- Generally it's best practice (but not a hard rule) to remove indexes and foreign keys in a post-deployment migration.
   - Exceptions include removing indexes and foreign keys for small tables.
 
 ### How to review for database
@@ -156,14 +156,14 @@ the following preparations into account.
 - Check migrations are reversible and implement a `#down` method
 - Check data migrations:
   - Establish a time estimate for execution on GitLab.com.
-  - Depending on timing, data migrations can be placed on regular, post-deploy or background migrations.
+  - Depending on timing, data migrations can be placed on regular, post-deploy, or background migrations.
   - Data migrations should be reversible too or come with a description of how to reverse, when possible.
     This applies to all types of migrations (regular, post-deploy, background).
 - Query performance
   - Check for any obviously complex queries and queries the author specifically
     points out for review (if any)
   - If not present yet, ask the author to provide SQL queries and query plans
-    (e.g. by using [chatops](understanding_explain_plans.md#chatops) or direct
+    (for example, by using [chatops](understanding_explain_plans.md#chatops) or direct
     database access)
   - For given queries, review parameters regarding data distribution
   - [Check query plans](understanding_explain_plans.md) and suggest improvements

doc/development/documentation/index.md

@@ -16,7 +16,7 @@ In addition to this page, the following resources can help you craft and contrib
 
 ## Source files and rendered web locations
 
-Documentation for GitLab, GitLab Runner, Omnibus GitLab and Charts is published to <https://docs.gitlab.com>. Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance.
+Documentation for GitLab, GitLab Runner, Omnibus GitLab, and Charts is published to <https://docs.gitlab.com>. Documentation for GitLab is also published within the application at `/help` on the domain of the GitLab instance.
 At `/help`, only help for your current edition and version is included. Help for other versions is available at <https://docs.gitlab.com/archives/>.
 
 The source of the documentation exists within the codebase of each GitLab application in the following repository locations:

doc/development/documentation/site_architecture/index.md

@@ -107,7 +107,7 @@ The pipeline in the `gitlab-docs` project:
 
 ### Rebuild the docs site Docker images
 
-Once a week, on Mondays, a scheduled pipeline runs and rebuilds the Docker images
+Once a week on Mondays, a scheduled pipeline runs and rebuilds the Docker images
 used in various pipeline jobs, like `docs-lint`. The Docker image configuration files are
 located at <https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master/dockerfiles>.
 
@@ -230,7 +230,7 @@ for its search function. This is how it works:
 NOTE: **For GitLab employees:**
 The credentials to access the Algolia dashboard are stored in 1Password. If you
 want to receive weekly reports of the search usage, search the Google doc with
-title "Email, Slack, and GitLab Groups and Aliases", search for `docsearch`,
+title `Email, Slack, and GitLab Groups and Aliases`, search for `docsearch`,
 and add a comment with your email to be added to the alias that gets the weekly
 reports.
 

doc/development/documentation/styleguide.md

@@ -17,14 +17,12 @@ that apply to all GitLab content, not just documentation.
 
 ### Why a single source of truth
 
-The documentation is the SSOT for all information related to the implementation, usage, and troubleshooting of GitLab products and features. It evolves continually, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness.
+The documentation of GitLab products and features is the SSOT for all information related to implementation, usage, and troubleshooting. It evolves continually, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness.
 
 This policy prevents information silos, ensuring that it remains easy to find information about GitLab products.
 
 It also informs decisions about the kinds of content we include in our documentation.
 
-The documentation is a continually evolving SSOT for all information related to the implementation, usage, and troubleshooting of GitLab products and features.
-
 ### All information
 
 Include problem-solving actions that may address rare cases or be considered 'risky', so long as proper context is provided in the form of fully detailed warnings and caveats. This kind of content should be included as it could be helpful to others and, when properly explained, its benefits outweigh the risks. If you think you have found an exception to this rule, contact the Technical Writing team.
@@ -34,7 +32,7 @@ For the Troubleshooting sections, people in GitLab Support can merge additions t
 
 ### All media types
 
-Include any media types/sources if the content is relevant to readers. You can freely include or link presentations, diagrams, videos, etc.; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it.
+Include any media types/sources if the content is relevant to readers. You can freely include or link presentations, diagrams, videos, and so on; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it.
 
 - If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone.
 - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source.
@@ -63,13 +61,17 @@ Instead, link to the SSOT and explain why it is important to consume the informa
 
 ### Organize by topic, not by type
 
-Beyond top-level audience-type folders (e.g. `administration`), we organize content by topic, not by type, so that it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter.
+Beyond top-level audience-type folders (for example, `administration`), we organize content by topic, not by type, so that it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter.
+
+For example, do not create groupings of similar media types. For example:
 
-For example, do not create groupings of similar media types (e.g. glossaries, FAQs, or sets of all articles or videos).
+- Glossaries.
+- FAQs.
+- Sets of all articles or videos.
 
 Such grouping of content by type makes
 it difficult to browse for the information you need and difficult to maintain up-to-date content.
-Instead, organize content by its subject (e.g. everything related to CI goes together)
+Instead, organize content by its subject (for example, everything related to CI goes together)
 and cross-link between any related content.
 
 ### Docs-first methodology
@@ -79,7 +81,10 @@ We employ a **docs-first methodology** to help ensure that the docs remain a com
 - If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information.
 - When you encounter new information not available in GitLab’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request (MR) to add this information to the docs. You can then share the MR in order to communicate this information.
 
-New information that would be useful toward the future usage or troubleshooting of GitLab should not be written directly in a forum or other messaging system, but added to a docs MR and then referenced, as described above. Note that among any other doc changes, you can always add a Troubleshooting section to a doc if none exists, or un-comment and use the placeholder Troubleshooting section included as part of our [doc template](structure.md#template-for-new-docs), if present.
+New information that would be useful toward the future usage or troubleshooting of GitLab should not be written directly in a forum or other messaging system, but added to a docs MR and then referenced, as described above. Note that among any other doc changes, you can either:
+
+- Add a Troubleshooting section to a doc if none exists.
+- Un-comment and use the placeholder Troubleshooting section included as part of our [doc template](structure.md#template-for-new-docs), if present.
 
 The more we reflexively add useful information to the docs, the more (and more successfully) the docs will be used to efficiently accomplish tasks and solve problems.
 
@@ -98,7 +103,7 @@ Ruby gem will support all [GFM markup](../../user/markdown.md) in the future. Th
 all markup that is supported for display in the GitLab application itself. For now,
 use regular Markdown markup, following the rules in the linked style guide.
 
-Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help).
+Note that Kramdown-specific markup (for example, `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help).
 
 Hard-coded HTML is valid, although it's discouraged to be used while we have `/help`. HTML is permitted as long as:
 
@@ -1149,7 +1154,7 @@ keyword "only":
 - For GitLab Premium: `**(PREMIUM ONLY)**`.
 - For GitLab Ultimate: `**(ULTIMATE ONLY)**`.
 
-For GitLab.com only tiers (when the feature is not available for self-hosted instances):
+For GitLab.com only tiers (when the feature is not available for self-managed instances):
 
 - For GitLab Free and higher tiers: `**(FREE ONLY)**`.
 - For GitLab Bronze and higher tiers: `**(BRONZE ONLY)**`.

doc/development/documentation/workflow.md

@@ -118,7 +118,7 @@ Reviewers help ensure:
 Prior to merging, documentation changes committed by the developer must be reviewed by:
 
 - The code reviewer for the merge request. This is known as a technical review.
-- Optionally, others involved in the work, such as other developers or the Product Manager.
+- Optionally, others involved in the work such as other developers or the Product Manager.
 - The Technical Writer for the DevOps stage group, except in exceptional circumstances where a
   [post-merge review](#post-merge-reviews) can be requested.
 - A maintainer of the project.
@@ -137,11 +137,11 @@ For issues requiring any new or updated documentation, the Product Manager must:
 - Confirm or add the [documentation requirements](#documentation-requirements).
 - Ensure the issue contains:
   - Any new or updated feature name.
-  - Overview, description, and use cases, as required by the
-    [documentation structure and template](structure.md), when applicable.
+  - Overview, description, and use cases when applicable (as required by the
+    [documentation structure and template](structure.md)).
 
-Everyone is encouraged to draft the documentation requirements in the issue, but a Product Manager
-will do the following:
+Everyone is encouraged to draft the documentation requirements in the issue. However, a Product
+Manager will:
 
 - When the issue is assigned a release milestone, review and update the Documentation details.
 - By the kickoff, finalize the documentation details.
@@ -238,7 +238,7 @@ The following details should be included:
 - What concepts and procedures should the documentation guide and enable the user to understand or
   accomplish?
 - To this end, what new page(s) are needed, if any? What pages or subsections need updates?
-  Consider user, admin, and API documentation changes and additions.
+  Consider changes and additions to user, admin, and API documentation.
 - For any guide or instruction set, should it help address a single use case, or be flexible to
   address a certain range of use cases?
 - Do we need to update a previously recommended workflow? Should we link the new feature from

doc/development/elasticsearch.md

@@ -36,7 +36,11 @@ Additionally, if you need large repos or multiple forks for testing, please cons
 
 The Elasticsearch integration depends on an external indexer. We ship an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). The user must trigger the initial indexing via a rake task but, after this is done, GitLab itself will trigger reindexing when required via `after_` callbacks on create, update, and destroy that are inherited from [/ee/app/models/concerns/elastic/application_versioned_search.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/models/concerns/elastic/application_versioned_search.rb).
 
-All indexing after the initial one is done via `ElasticIndexerWorker` (Sidekiq jobs).
+After initial indexing is complete, updates proceed in one of two ways, depending on the `:elastic_bulk_incremental_updates` feature flag.
+
+If disabled, every create, update, or delete operation on an Elasticsearch-tracked model enqueues a new `ElasticIndexerWorker` Sidekiq job which takes care of updating just that document. This is quite inefficient.
+
+If the feature flag is enabled, create, update, and delete operations for all models except projects (see [#207494](https://gitlab.com/gitlab-org/gitlab/issues/207494)) are tracked in a Redis [`ZSET`](https://redis.io/topics/data-types#sorted-sets) instead. A regular `sidekiq-cron` `ElasticIndexBulkCronWorker` processes this queue, updating many Elasticsearch documents at a time with the [Bulk Request API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html).
 
 Search queries are generated by the concerns found in [ee/app/models/concerns/elastic](https://gitlab.com/gitlab-org/gitlab/tree/master/ee/app/models/concerns/elastic). These concerns are also in charge of access control, and have been a historic source of security bugs so please pay close attention to them!
 

doc/development/event_tracking/index.md

@@ -13,7 +13,7 @@ As developers, we should attempt to add tracking and instrumentation where possi
 - Usage patterns.
 - Other metrics that can potentially be improved on.
 
-To maintain consistency, and not adversely effect performance, we have some basic tracking functionality exposed at both the frontend and backend layers that can be utilized while building new features or updating existing features.
+To maintain consistency and not adversely effect performance, we have some basic tracking functionality exposed at both the frontend and backend layers that can be utilized while building new features or updating existing features.
 
 We also encourage users to enable tracking, and we embrace full transparency with our tracking approach so it can be easily understood and trusted. By enabling tracking, users can:
 

doc/development/fe_guide/development_process.md

@@ -71,7 +71,7 @@ With the purpose of being [respectful of others' time](https://about.gitlab.com/
   - includes tests
   - includes a changelog entry (when necessary)
 - Before assigning to a maintainer, assign to a reviewer.
-- If you assigned a merge request, or pinged someone directly, keep in mind that we work in different timezones and asynchronously, so be patient. Unless the merge request is urgent (like fixing a broken master), please don't DM or reassign the merge request before waiting for a 24-hour window.
+- If you assigned a merge request or pinged someone directly, be patient because we work in different timezones and asynchronously. Unless the merge request is urgent (like fixing a broken master), please don't DM or reassign the merge request before waiting for a 24-hour window.
 - If you have a question regarding your merge request/issue, make it on the merge request/issue. When we DM each other, we no longer have a SSOT and [no one else is able to contribute](https://about.gitlab.com/handbook/values/#public-by-default).
 - When you have a big WIP merge request with many changes, you're advised to get the review started before adding/removing significant code. Make sure it is assigned well before the release cut-off, as the reviewer(s)/maintainer(s) would always prioritize reviewing finished MRs before WIP ones.
 - Make sure to remove the WIP title before the last round of review.

doc/development/fe_guide/graphql.md

@@ -53,7 +53,7 @@ fragment DesignListItem on Design {
 }
 ```
 
-Fragments can be stored in separate files, imported and used in queries, mutations or other fragments.
+Fragments can be stored in separate files, imported and used in queries, mutations, or other fragments.
 
 ```javascript
 #import "./designList.fragment.graphql"

doc/development/fe_guide/vuex.md

@@ -6,7 +6,7 @@ _Note:_ All of the below is explained in more detail in the official [Vuex docum
 
 ## Separation of concerns
 
-Vuex is composed of State, Getters, Mutations, Actions and Modules.
+Vuex is composed of State, Getters, Mutations, Actions, and Modules.
 
 When a user clicks on an action, we need to `dispatch` it. This action will `commit` a mutation that will change the state.
 _Note:_ The action itself will not update the state, only a mutation should update the state.

doc/development/feature_flags/process.md

@@ -53,7 +53,7 @@ absolutely no way to use the feature until it is enabled.
 
 ### Including a feature behind feature flag in the final release
 
-In order to build a final release and present the feature for self-hosted
+In order to build a final release and present the feature for self-managed
 users, the feature flag should be at least defaulted to **on**. If the feature
 is deemed stable and there is confidence that removing the feature flag is safe,
 consider removing the feature flag altogether.
@@ -126,8 +126,11 @@ need to revert a release, and because feature flags are disabled by default we
 don't need to revert and pick any Git commits. In fact, all we have to do is
 disable the feature, and in the worst case, perform cleanup. Let's say that
 the cost of this is 2. In this case, our best case cost is 11: 10 to build the
-feature, and 1 to add the feature flag. The worst case cost is now 13: 10 to
-build the feature, 1 to add the feature flag, and 2 to disable and clean up.
+feature, and 1 to add the feature flag. The worst case cost is now 13:
+
+- 10 to build the feature.
+- 1 to add the feature flag.
+- 2 to disable and clean up.
 
 Here we can see that in the best case scenario the work necessary is only a tiny
 bit more compared to not using a feature flag. Meanwhile, the process of

doc/development/new_fe_guide/development/accessibility.md

@@ -4,7 +4,7 @@ Using semantic HTML plays a key role when it comes to accessibility.
 
 ## Accessible Rich Internet Applications - ARIA
 
-WAI-ARIA, the Accessible Rich Internet Applications specification, defines a way to make Web content and Web applications more accessible to people with disabilities.
+WAI-ARIA (the Accessible Rich Internet Applications specification) defines a way to make Web content and Web applications more accessible to people with disabilities.
 
 > Note: It is [recommended][using-aria] to use semantic elements as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements.
 

doc/development/new_fe_guide/index.md

 # Frontend Development Guidelines
 
 This guide contains all the information to successfully contribute to GitLab's frontend.
-This is a living document, and we welcome contributions, feedback and suggestions.
+This is a living document, and we welcome contributions, feedback, and suggestions.
 
 ## [Development](development/index.md)
 

doc/development/packages.md

@@ -75,8 +75,8 @@ that gives a way to identify the project that the package belongs to. This gener
 id or full project path in the package name. See
 [Conan's naming convention](../user/packages/conan_repository/index.md#package-recipe-naming-convention) as an example.
 
-For group and project-level endpoints, naming can be less constrained, and it will be up to the group and project
-members to be certain that there is no conflict between two package names, however the system should prevent
+For group and project-level endpoints, naming can be less constrained and it will be up to the group and project
+members to be certain that there is no conflict between two package names. However, the system should prevent
 a user from reusing an existing name within a given scope.
 
 Otherwise, naming should follow the package manager's naming conventions and include a validation in the `package.md`

doc/development/performance.md

@@ -259,10 +259,10 @@ One of the reasons of the increased memory footprint could be Ruby memory fragme
 
 To diagnose it, you can visualize Ruby heap as described in [this post by Aaron Patterson](https://tenderlovemaking.com/2017/09/27/visualizing-your-ruby-heap.html).
 
-To start, you want to dump the heap of the process you're investigating to a JSON file.  
+To start, you want to dump the heap of the process you're investigating to a JSON file.
 
-You need to run the command inside the process you're exploring, you may do that with `rbtrace`.  
-`rbtrace` is already present in GitLab `Gemfile`, you just need to require it.  
+You need to run the command inside the process you're exploring, you may do that with `rbtrace`.
+`rbtrace` is already present in GitLab `Gemfile`, you just need to require it.
 It could be achieved running webserver or Sidekiq with the environment variable set to `ENABLE_RBTRACE=1`.
 
 To get the heap dump:
@@ -281,7 +281,7 @@ Fragmented Ruby heap snapshot could look like this:
 
 ![Ruby heap fragmentation](img/memory_ruby_heap_fragmentation.png)
 
-Memory fragmentation could be reduced by tuning GC parameters as described in [this post by Nate Berkopec](https://www.speedshop.co/2017/12/04/malloc-doubles-ruby-memory.html), which should be considered as a tradeoff, as it may affect overall performance of memory allocation and GC cycles.
+Memory fragmentation could be reduced by tuning GC parameters as described in [this post by Nate Berkopec](https://www.speedshop.co/2017/12/04/malloc-doubles-ruby-memory.html). This should be considered as a tradeoff, as it may affect overall performance of memory allocation and GC cycles.
 
 ## Importance of Changes
 

doc/development/redis.md

@@ -8,7 +8,7 @@ GitLab uses [Redis](https://redis.io) for three distinct purposes:
 
 Every application process is configured to use the same Redis servers, so they
 can be used for inter-process communication in cases where [PostgreSQL](sql.md)
-is less appropriate, for example, transient state or data that is written much
+is less appropriate. For example, transient state or data that is written much
 more often than it is read.
 
 If [Geo](geo.md) is enabled, each Geo node gets its own, independent Redis

doc/development/sidekiq_style_guide.md

@@ -66,7 +66,7 @@ are not adjusted appropriately.
 
 ## Idempotent Jobs
 
-It's known that a job can fail for multiple reasons, for example, network outages or bugs.
+It's known that a job can fail for multiple reasons. For example, network outages or bugs.
 In order to address this, Sidekiq has a built-in retry mechanism that is
 used by default by most workers within GitLab.
 
@@ -178,7 +178,7 @@ end
 ## Jobs with External Dependencies
 
 Most background jobs in the GitLab application communicate with other GitLab
-services, eg Postgres, Redis, Gitaly and Object Storage. These are considered
+services. For example, Postgres, Redis, Gitaly, and Object Storage. These are considered
 to be "internal" dependencies for a job.
 
 However, some jobs will be dependent on external services in order to complete
@@ -388,7 +388,7 @@ requests. We do this to avoid incorrect metadata when other jobs are
 scheduled from the cron-worker.
 
 Cron-Workers themselves run instance wide, so they aren't scoped to
-users, namespaces, projects or other resources that should be added to
+users, namespaces, projects, or other resources that should be added to
 the context.
 
 However, they often schedule other jobs that _do_ require context.

doc/development/testing_guide/end_to_end/quick_start_guide.md

@@ -2,7 +2,12 @@
 
 In this tutorial, you will find different examples, and the steps involved, in the creation of end-to-end (_e2e_) tests for GitLab CE and GitLab EE, using GitLab QA.
 
-> When referring to end-to-end tests in this document, this means testing a specific feature end-to-end, such as a user logging in, the creation of a project, the management of labels, breaking down epics into sub-epics and issues, etc.
+When referring to end-to-end tests in this document, this means testing a specific feature end-to-end such as:
+
+- A user logging in.
+- The creation of a project.
+- The management of labels.
+- Breaking down epics into sub-epics and issues.
 
 ## Important information before we start writing tests
 
@@ -209,7 +214,11 @@ First, we remove the duplication of strings by defining the global variables `@i
 
 Then, by creating a reusable `select_label_and_refresh` method, we remove the code duplication of this action, and later we can move this method to a Page Object class that will be created for easier maintenance purposes.
 
-> Notice that the reusable method is created at the bottom of the file. The reason for that is that reading the code should be similar to reading a newspaper, where high-level information is at the top, like the title and summary of the news, while low level, or more specific information, is at the bottom (this helps readability).
+Notice that the reusable method is created at the bottom of the file. This helps readability,
+where reading the code should be similar to reading a newspaper:
+
+- High-level information is at the top, like the title and summary of the news.
+- Low level, or more specific information, is at the bottom.
 
 ### 5. Tests' pre-conditions using resources and Page Objects
 
@@ -353,7 +362,7 @@ You can think of [Resources] as anything that can be created on GitLab CE or EE,
 
 With that in mind, resources can be a project, an epic, an issue, a label, a commit, etc.
 
-As you saw in the tests' pre-conditions and the optimization sections, we're already creating some of these resources, and we are doing that by calling the `fabricate_via_api!` method.
+As you saw in the tests' pre-conditions and the optimization sections, we're already creating some of these resources. We are doing that by calling the `fabricate_via_api!` method.
 
 > We could be using the `fabricate!` method instead, which would use the `fabricate_via_api!` method if it exists, and fallback to GUI fabrication otherwise, but we recommend being explicit to make it clear what the test does. Also, we always recommend fabricating resources via API since this makes tests faster and more reliable.
 

doc/development/testing_guide/testing_levels.md

@@ -103,7 +103,7 @@ graph RL
   For complex Vuex mutations, you should separate the tests from other parts of the Vuex store to simplify problem-solving.
 
 #### When *not* to use unit tests
-  
+
 - **Non-exported functions or classes**:
   Anything not exported from a module can be considered private or an implementation detail, and doesn't need to be tested.
 - **Constants**:
@@ -200,7 +200,7 @@ graph RL
 - **All server requests**:
   Similar to unit tests, when running component tests, the backend may not be reachable, so all outgoing requests need to be mocked.
 - **Asynchronous background operations**:
-  Similar to unit tests, background operations cannot be stopped or waited on, so they will continue running in the following tests and cause side effects.
+  Similar to unit tests, background operations cannot be stopped or waited on. This means they will continue running in the following tests and cause side effects.
 - **Child components**:
   Every component is tested individually, so child components are mocked.
   See also [`shallowMount()`](https://vue-test-utils.vuejs.org/api/#shallowmount)

doc/integration/elasticsearch.md

@@ -260,7 +260,7 @@ If the database size is less than 500 MiB, and the size of all hosted repos is l
 
 CAUTION: **Warning**:
 Performing asynchronous indexing will generate a lot of Sidekiq jobs.
-Make sure to prepare for this task by either [Horizontally Scaling](../administration/high_availability/README.md#basic-scaling)
+Make sure to prepare for this task by having a [Scalable and Highly Available Setup](README.md)
 or creating [extra Sidekiq processes](../administration/operations/extra_sidekiq_processes.md)
 
 1. [Configure your Elasticsearch host and port](#enabling-elasticsearch).

doc/integration/omniauth.md

@@ -51,7 +51,7 @@ that are in common for all providers that we need to consider.
   be created manually or they will not be able to sign in via OmniAuth.
 - `auto_link_ldap_user` can be used if you have [LDAP / ActiveDirectory](ldap.md)
   integration enabled. It defaults to false. When enabled, users automatically
-  created through OmniAuth will be linked to their LDAP entry as well.
+  created through an OmniAuth provider will have their LDAP identity created in GitLab as well.
 - `block_auto_created_users` defaults to `true`. If `true` auto created users will
   be blocked by default and will have to be unblocked by an administrator before
   they are able to sign in.

doc/integration/saml.md

@@ -188,7 +188,7 @@ tell GitLab which groups are external via the `external_groups:` element:
         } }
 ```
 
-## Required groups
+## Required groups **(STARTER ONLY)**
 
 >**Note:**
 This setting is only available on GitLab 10.2 EE and above.
@@ -215,7 +215,7 @@ Example:
         } }
 ```
 
-## Admin Groups
+## Admin Groups **(STARTER ONLY)**
 
 >**Note:**
 This setting is only available on GitLab 8.8 EE and above.
@@ -239,7 +239,7 @@ considered `admin groups`.
         } }
 ```
 
-## Auditor Groups
+## Auditor Groups **(STARTER ONLY)**
 
 >**Note:**
 This setting is only available on GitLab 11.4 EE and above.

doc/user/markdown.md

@@ -131,26 +131,26 @@ Supported formats (named colors are not supported):
 Color written inside backticks will be followed by a color "chip":
 
 ```markdown
-`#F00`  
-`#F00A`  
-`#FF0000`  
-`#FF0000AA`  
-`RGB(0,255,0)`  
-`RGB(0%,100%,0%)`  
-`RGBA(0,255,0,0.3)`  
-`HSL(540,70%,50%)`  
-`HSLA(540,70%,50%,0.3)`  
-```
-
-`#F00`  
-`#F00A`  
-`#FF0000`  
-`#FF0000AA`  
-`RGB(0,255,0)`  
-`RGB(0%,100%,0%)`  
-`RGBA(0,255,0,0.3)`  
-`HSL(540,70%,50%)`  
-`HSLA(540,70%,50%,0.3)`  
+- `#F00`
+- `#F00A`
+- `#FF0000`
+- `#FF0000AA`
+- `RGB(0,255,0)`
+- `RGB(0%,100%,0%)`
+- `RGBA(0,255,0,0.3)`
+- `HSL(540,70%,50%)`
+- `HSLA(540,70%,50%,0.3)`
+```
+
+- `#F00`
+- `#F00A`
+- `#FF0000`
+- `#FF0000AA`
+- `RGB(0,255,0)`
+- `RGB(0%,100%,0%)`
+- `RGBA(0,255,0,0.3)`
+- `HSL(540,70%,50%)`
+- `HSLA(540,70%,50%,0.3)`
 
 ### Diagrams and flowcharts
 
@@ -390,7 +390,7 @@ the [asciidoctor user manual](https://asciidoctor.org/docs/user-manual/#activati
 ### Special GitLab references
 
 GFM recognizes special GitLab related references. For example, you can easily reference
-an issue, a commit, a team member or even the whole team within a project. GFM will turn
+an issue, a commit, a team member, or even the whole team within a project. GFM will turn
 that reference into a link so you can navigate between them easily.
 
 Additionally, GFM recognizes certain cross-project references, and also has a shorthand
@@ -581,7 +581,7 @@ Quote break.
 GFM extends the standard Markdown standard by also supporting multiline blockquotes
 fenced by `>>>`:
 
-```
+```markdown
 >>>
 If you paste a message from somewhere else
 
@@ -630,7 +630,7 @@ def function():
     3-backtick fences.
 ~~~
 
-```
+```plaintext
 ~~~
 Tildes are OK too.
 ~~~
@@ -638,20 +638,20 @@ Tildes are OK too.
 
 The three examples above render as:
 
-```
+```python
 def function():
     #indenting works just fine in the fenced code block
     s = "Python code"
     print s
 ```
 
-```
+```plaintext
 Using 4 spaces
 is like using
 3-backtick fences.
 ```
 
-~~~
+~~~plaintext
 Tildes are OK too.
 ~~~
 
@@ -668,7 +668,7 @@ code when it is inline.
 Blocks of code are fenced by lines with three back-ticks ```` ``` ```` or three tildes `~~~`, and have
 the language identified at the end of the first fence:
 
-~~~
+~~~markdown
 ```javascript
 var s = "JavaScript syntax highlighting";
 alert(s);
@@ -714,7 +714,7 @@ markdown = Redcarpet.new("Hello World!")
 puts markdown.to_html
 ```
 
-```
+```plaintext
 No language indicated, so no syntax highlighting.
 s = "There is no highlighting for this."
 But let's throw in a <b>tag</b>.
@@ -756,7 +756,7 @@ dealing with code and names that often appear with multiple underscores. As a re
 GFM extends the standard Markdown standard by ignoring multiple underlines in words,
 to allow better rendering of Markdown documents discussing code:
 
-```md
+```markdown
 perform_complicated_task
 
 do_this_and_do_that_and_another_thing
@@ -852,7 +852,7 @@ The IDs are generated from the content of the header according to the following
 
 Example:
 
-```
+```markdown
 # This header has spaces in it
 ## This header has a :thumbsup: in it
 # This header has Unicode in it: 한글
@@ -973,7 +973,7 @@ class for the list of allowed HTML tags and attributes. In addition to the defau
   <dd>Is something people use sometimes.</dd>
 
   <dt>Markdown in HTML</dt>
-  <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>always</b> work.</dd>
+  <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>work</b>, in most cases.</dd>
 </dl>
 ```
 
@@ -982,7 +982,7 @@ class for the list of allowed HTML tags and attributes. In addition to the defau
   <dd>Is something people use sometimes.</dd>
 
   <dt>Markdown in HTML</dt>
-  <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>always</b> work.</dd>
+  <dd>Does *not* work **very** well. HTML <em>tags</em> will <b>work</b>, in most cases.</dd>
 </dl>
 
 ---
@@ -993,12 +993,12 @@ are separated into their own lines:
 ```html
 <dl>
   <dt>Markdown in HTML</dt>
-  <dd>Does *not* work **very** well. HTML tags will always work.</dd>
+  <dd>Does *not* work **very** well. HTML tags will work, in most cases.</dd>
 
   <dt>Markdown in HTML</dt>
   <dd>
 
-  Does *not* work **very** well. HTML tags will always work.
+  Does *not* work **very** well. HTML tags will work, in most cases.
 
   </dd>
 </dl>
@@ -1008,12 +1008,12 @@ are separated into their own lines:
 
 <dl>
   <dt>Markdown in HTML</dt>
-  <dd>Does *not* work **very** well. HTML tags will always work.</dd>
+  <dd>Does *not* work **very** well. HTML tags will work, in most cases.</dd>
 
   <dt>Markdown in HTML</dt>
   <dd>
 
-  Does <em>not</em> work <b>very</b> well. HTML tags will always work.
+  Does <em>not</em> work <b>very</b> well. HTML tags will work, in most cases.
 
   </dd>
 </dl>
@@ -1148,7 +1148,7 @@ A new line due to the previous backslash.
 
 There are two ways to create links, inline-style and reference-style:
 
-```md
+```markdown
 - This is an [inline-style link](https://www.google.com)
 - This is a [link to a repository file in the same directory](index.md)
 - This is a [relative link to a readme one directory higher](../README.md)
@@ -1319,7 +1319,7 @@ the paragraph will appear outside the list, instead of properly indented under t
 
 Example:
 
-```
+```markdown
 1. First ordered list item
 
   Paragraph of first item.

doc/user/packages/conan_repository/index.md

@@ -39,7 +39,7 @@ conan --version
 
 You should see the Conan version printed in the output:
 
-```
+```plaintext
 Conan version 1.20.5
 ```
 

doc/user/packages/npm_registry/index.md

@@ -49,7 +49,7 @@ npm --version
 
 You should see the NPM version printed in the output:
 
-```
+```plaintext
 6.10.3
 ```
 
@@ -67,7 +67,7 @@ yarn --version
 
 You should see the version printed like so:
 
-```
+```plaintext
 1.19.1
 ```
 

doc/user/packages/nuget_repository/index.md

@@ -26,7 +26,7 @@ nuget help
 
 You should see something similar to:
 
-```
+```plaintext
 NuGet Version: 5.2.0.6090
 usage: NuGet <command> [args] [options]
 Type 'NuGet help <command>' for help on a specific command.

doc/user/profile/account/two_factor_authentication.md

@@ -160,6 +160,7 @@ have lost your code generation device) you can:
 
 - [Use a saved recovery code](#use-a-saved-recovery-code).
 - [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh).
+- [Regenerate 2FA recovery codes](#regenerate-2fa-recovery-codes).
 - [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account).
 
 ### Use a saved recovery code
@@ -219,6 +220,20 @@ a new set of recovery codes with SSH:
 After signing in, visit your **Profile settings > Account**  immediately to set
 up two-factor authentication with a new device.
 
+### Regenerate 2FA recovery codes
+
+To regenerate 2FA recovery codes, you need access to a desktop browser:
+
+1. Navigate to GitLab.
+1. Sign in to your GitLab account.
+1. Go to your [Profile settings](../index.md#profile-settings).
+1. Select **{account}** **Account > Two-Factor Authentication (2FA)**.
+1. If you've already configured 2FA, click **Manage two-factor authentication**.
+1. In the **Register Two-Factor Authenticator** pane, click **Regenerate recovery codes**.
+
+NOTE: **Note:**
+If you regenerate 2FA recovery codes, save them. You won't be able to use any previously created 2FA codes.
+
 ### Ask a GitLab administrator to disable two-factor authentication on your account
 
 If you cannot use a saved recovery code or generate new recovery codes, ask a

doc/user/project/clusters/add_remove_clusters.md

@@ -5,7 +5,7 @@ GitLab offers integrated cluster creation for the following Kubernetes providers
 - Google Kubernetes Engine (GKE).
 - Amazon Elastic Kubernetes Service (EKS).
 
-In addition, GitLab can integrate with any standard Kubernetes provider, either on-premise or hosted.
+GitLab can also integrate with any standard Kubernetes provider, either on-premise or hosted.
 
 TIP: **Tip:**
 Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial),

doc/user/project/deploy_tokens/index.md

@@ -9,11 +9,11 @@ at midnight UTC and that they can be only managed by [maintainers](../../permiss
 
 ## Creating a Deploy Token
 
-You can create as many deploy tokens as you like from the settings of your project:
+You can create as many deploy tokens as you like from the settings of your project. Alternatively, you can also create [group-scoped deploy tokens](#group-deploy-token).
 
 1. Log in to your GitLab account.
-1. Go to the project you want to create Deploy Tokens for.
-1. Go to **Settings** > **Repository**.
+1. Go to the project (or group) you want to create Deploy Tokens for.
+1. Go to **{settings}** **Settings** > **CI / CD**.
 1. Click on "Expand" on **Deploy Tokens** section.
 1. Choose a name, expiry date (optional), and username (optional) for the token.
 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token).
@@ -77,6 +77,22 @@ docker login -u <username> -p <deploy_token> registry.example.com
 Just replace `<username>` and `<deploy_token>` with the proper values. Then you can simply
 pull images from your Container Registry.
 
+### Group Deploy Token
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/21765) in GitLab 12.9.
+
+A deploy token created at the group level can be used across all projects that
+belong either to the specific group or to one of its subgroups.
+
+To use a group deploy token:
+
+1. [Create](#creating-a-deploy-token) a deploy token for a group.
+1. Use it the same way you use a project deploy token when
+   [cloning a repository](#git-clone-a-repository).
+
+The scopes applied to a group deploy token (such as `read_repository`) will
+apply consistently when cloning the repository of related projects.
+
 ### GitLab Deploy Token
 
 > [Introduced][ce-18414] in GitLab 10.8.

doc/user/project/description_templates.md

@@ -91,7 +91,7 @@ It is possible to use [quick actions](quick_actions.md) within description templ
 
 Here is an example for a Bug report template:
 
-```
+```plaintext
 Summary
 
 (Summarize the bug encountered concisely)

doc/user/project/import/github.md

@@ -40,10 +40,13 @@ in which case it defaults to the default project visibility.
 When issues and pull requests are being imported, the importer attempts to find their GitHub authors and
 assignees in the database of the GitLab instance (note that pull requests are called "merge requests" in GitLab).
 
-For this association to succeed, prior to the import, each GitHub author and assignee in the repository must
-have either previously logged in to a GitLab account using the GitHub icon **or** have a GitHub account with
-a [primary email address](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) that
-matches their GitLab account's email address.
+For this association to succeed, each GitHub author and assignee in the repository
+must meet one of the following conditions prior to the import:
+
+- Have previously logged in to a GitLab account using the GitHub icon.
+- Have a GitHub account with a
+  [primary email address](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address)
+  that matches their GitLab account's email address.
 
 If a user referenced in the project is not found in GitLab's database, the project creator (typically the user
 that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original

doc/user/project/import/index.md

@@ -24,7 +24,7 @@ There is also the option of [connecting your external repository to get CI/CD be
 
 ## Migrating from self-hosted GitLab to GitLab.com
 
-If you only need to migrate Git repos, you can [import each project by URL](repo_by_url.md), but issues and merge requests can't be imported.
+If you only need to migrate Git repos, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported.
 
 If you want to retain all metadata like issues and merge requests, you can use
 the [import/export feature](../settings/import_export.md) to export projects from self-hosted GitLab and import those projects into GitLab.com.

doc/user/project/index.md

@@ -94,7 +94,7 @@ When you create a project in GitLab, you'll have access to a large number of
   your code blocks, overriding GitLab's default choice of language.
 - [Badges](badges.md): badges for the project overview.
 - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of
-  the source, build output, and other metadata or artifacts
+  the source, build output, other metadata, and other artifacts
   associated with a released version of your code.
 - [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab. **(PREMIUM)**
 - [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. **(PREMIUM)**