Add latest changes from gitlab-org/gitlab@master

12 files changed, 194 insertions, 60 deletions

diff --git a/doc/administration/geo/glossary.md b/doc/administration/geo/glossary.md
index 1ec552326aa..f8769d31ec7 100644
--- a/doc/administration/geo/glossary.md
+++ b/doc/administration/geo/glossary.md
@@ -21,7 +21,7 @@ these definitions yet.
 
 | Term                      | Definition                                                                                                                                                                             | Scope        | Discouraged synonyms                            |
 |---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|-------------------------------------------------|
-| Node                      | An individual server that runs GitLab either with a specific role or as a whole (e.g. a Rails application node). In a cloud context this can be a specific machine type.                 | GitLab       | instance, server                                |
+| Node                      | An individual server that runs GitLab either with a specific role or as a whole (for example a Rails application node). In a cloud context this can be a specific machine type.                 | GitLab       | instance, server                                |
 | Site                      | One or a collection of nodes running a single GitLab application. A site can be single-node or multi-node.                                                                             | GitLab       | deployment, installation instance               |
 | Single-node site          | A specific configuration of GitLab that uses exactly one node.                                                                                                                     | GitLab       | single-server, single-instance
 | Multi-node site           | A specific configuration of GitLab that uses more than one node.                                                                                                                   | GitLab       | multi-server, multi-instance, high availability |
@@ -31,7 +31,7 @@ these definitions yet.
 | Reference architecture(s) | A [specified configuration of GitLab for a number of users](../reference_architectures/index.md), possibly including multiple nodes and multiple sites. | GitLab       |                                                 |
 | Promoting                 | Changing the role of a site from secondary to primary.                                                                                                                                 | Geo-specific |                                                 |
 | Demoting                  | Changing the role of a site from primary to secondary.                                                                                                                                 | Geo-specific |                                                 |
-| Failover                  | The entire process that shifts users from a primary Site to a secondary site. This includes promoting a secondary, but contains other parts as well e.g. scheduling maintenance.       | Geo-specific |                                                 |
+| Failover                  | The entire process that shifts users from a primary Site to a secondary site. This includes promoting a secondary, but contains other parts as well. For example, scheduling maintenance.       | Geo-specific |                                                 |
 
 ## Examples
 
diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md
index 6e0ba8fa33f..96df93848dc 100644
--- a/doc/ci/pipeline_editor/index.md
+++ b/doc/ci/pipeline_editor/index.md
@@ -15,7 +15,7 @@ the `.gitlab-ci.yml` file in the root of your repository. To access the editor,
 
 From the pipeline editor page you can:
 
-- Select the branch to work from. [Introduced in GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/326189), disabled by default.
+- Select the branch to work from.
 - [Validate](#validate-ci-configuration) your configuration syntax while editing the file.
 - Do a deeper [lint](#lint-ci-configuration) of your configuration, that verifies it with any configuration
   added with the [`include`](../yaml/index.md#include) keyword.
@@ -85,6 +85,9 @@ where:
   [extended configuration merged into the job](../yaml/index.md#merge-details).
 - YAML anchors are [replaced with the linked configuration](../yaml/index.md#anchors).
 
+NOTE:
+You can only see the expanded view when editing the [default branch](../../user/project/repository/branches/default.md).
+
 ## Commit changes to CI configuration
 
 The commit form appears at the bottom of each tab in the editor so you can commit
diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md
index 8aab7db04f8..db6fa7f4d23 100644
--- a/doc/ci/pipelines/settings.md
+++ b/doc/ci/pipelines/settings.md
@@ -104,10 +104,10 @@ To customize the path:
 1. On the top bar, select **Menu > Projects** and find your project.
 1. On the left sidebar, select **Settings > CI/CD**.
 1. Expand **General pipelines**.
-1. In the **CI/CD configuration file** field, enter the file name, and if:
-   - The file is not in the root directory, include the path.
-   - The file is in a different project, include the group and project name.
-   - The file is on an external site, enter the full URL.
+1. In the **CI/CD configuration file** field, enter the filename. If the file:
+   - Is not in the root directory, include the path.
+   - Is in a different project, include the group and project name.
+   - Is on an external site, enter the full URL.
 1. Select **Save changes**.
 
 ### Custom CI/CD configuration file examples
@@ -122,7 +122,7 @@ If the CI/CD configuration file is on an external site, the URL must end with `.
 
 - `http://example.com/generate/ci/config.yml`
 
-If the CI/CD configuration file is in a different project in GitLab, the path must be relative
+If the CI/CD configuration file is in a different project, the path must be relative
 to the root directory in the other project. Include the group and project name at the end:
 
 - `.gitlab-ci.yml@mygroup/another-project`
@@ -173,31 +173,32 @@ In GitLab 12.0 and later, newly created projects automatically have a default
 This value can be overridden by the [`GIT_DEPTH` variable](../large_repositories/index.md#shallow-cloning)
 in the `.gitlab-ci.yml` file.
 
-## Timeout
+## Set a limit for how long jobs can run
 
-Timeout defines the maximum amount of time in minutes that a job is able run.
-This is configurable under your project's **Settings > CI/CD > General pipelines settings**.
-The default value is 60 minutes. Decrease the time limit if you want to impose
-a hard limit on your jobs' running time or increase it otherwise. In any case,
-if the job surpasses the threshold, it is marked as failed.
+You can define how long a job can run before it times out.
 
-### Timeout overriding for runners
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Settings > CI/CD**.
+1. Expand **General pipelines**.
+1. In the **Timeout** field, enter the number of minutes, or a human-readable value like `2 hours`.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17221) in GitLab 10.7.
+Jobs that exceed the timeout are marked as failed.
 
-Project defined timeout (either specific timeout set by user or the default
-60 minutes timeout) may be [overridden for runners](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner).
+You can override this value [for individual runners](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner).
 
-## Test coverage parsing
+## Add test coverage results to a merge request
 
-If you use test coverage in your code, GitLab can capture its output in the
-job log using a regular expression.
+If you use test coverage in your code, you can use a regular expression to
+find coverage results in the job log. You can then include these results
+in the merge request in GitLab.
 
-In your project, go to **Settings > CI/CD** and expand the **General pipelines**
-section. Enter the regular expression in the **Test coverage parsing** field.
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Settings > CI/CD**.
+1. Expand **General pipelines**.
+1. In the **Test coverage parsing** field, enter a regular expression.
+   Leave blank to disable this feature.
 
-Leave blank if you want to disable it or enter a Ruby regular expression. You
-can use <https://rubular.com> to test your regex. The regex returns the **last**
+You can use <https://rubular.com> to test your regex. The regex returns the **last**
 match found in the output.
 
 If the pipeline succeeds, the coverage is shown in the merge request widget and
@@ -208,6 +209,10 @@ averaged.
 
 ![Build status coverage](img/pipelines_test_coverage_build.png)
 
+### Test coverage examples
+
+Use this regex for commonly used test tools.
+
 <!-- vale gitlab.Spelling = NO -->
 
 - Simplecov (Ruby). Example: `\(\d+.\d+\%\) covered`.
@@ -221,21 +226,25 @@ averaged.
 - `mix test --cover` (Elixir). Example: `\d+.\d+\%\s+\|\s+Total`.
 - JaCoCo (Java/Kotlin). Example: `Total.*?([0-9]{1,3})%`.
 - `go test -cover` (Go). Example: `coverage: \d+.\d+% of statements`.
-- .Net (OpenCover). Example: `(Visited Points).*\((.*)\)`.
-- .Net (`dotnet test` line coverage). Example: `Total\s*\|\s*(\d+(?:\.\d+)?)`.
+- .NET (OpenCover). Example: `(Visited Points).*\((.*)\)`.
+- .NET (`dotnet test` line coverage). Example: `Total\s*\|\s*(\d+(?:\.\d+)?)`.
 
 <!-- vale gitlab.Spelling = YES -->
 
-### Code coverage history
+### View code coverage history
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209121) the ability to download a `.csv` in GitLab 12.10.
 > - [Graph introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1.
 
 To see the evolution of your project code coverage over time,
-you can view a graph or download a CSV file with this data. From your project:
+you can view a graph or download a CSV file with this data.
 
-1. Go to **Project Analytics > Repository** to see the historic data for each job listed in the dropdown above the graph.
-1. If you want a CSV file of that data, click **Download raw data (`.csv`)**
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Analytics > Repository**.
+
+The historic data for each job is listed in the dropdown above the graph.
+
+To view a CSV file of the data, select **Download raw data (`.csv`)**.
 
 ![Code coverage graph of a project over time](img/code_coverage_graph_v13_1.png)
 
@@ -261,7 +270,7 @@ Follow these steps to enable the `Coverage-Check` MR approval rule:
 
 ![Coverage-Check approval rule](img/coverage_check_approval_rule_14_1.png)
 
-### Removing color codes
+### Remove color codes from code coverage
 
 Some test coverage tools output with ANSI color codes that aren't
 parsed correctly by the regular expression. This causes coverage
@@ -279,13 +288,18 @@ lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g'
 
 ## Pipeline badges
 
-In the pipelines settings page you can find pipeline status and test coverage
-badges for your project. The latest successful pipeline is used to read
-the pipeline status and test coverage values.
+Pipeline badges indicate the pipeline status and a test coverage value
+for your project. These badges are determined by the latest successful pipeline.
+
+### View the code for the pipeline status and coverage reports badges
 
-Visit the pipelines settings page in your project to see the exact link to
-your badges. You can also see ways to embed the badge image in your HTML or Markdown
-pages.
+You can view the exact link for your badges. Then you can embed the badge in your HTML
+or Markdown pages.
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Settings > CI/CD**.
+1. Expand **General pipelines**.
+1. In the **Pipeline status** or **Coverage report** sections, view the URLs for the images.
 
 ![Pipelines badges](img/pipelines_settings_badges.png)
 
@@ -301,7 +315,7 @@ Depending on the status of your pipeline, a badge can have the following values:
 - `canceled`
 - `unknown`
 
-You can access a pipeline status badge image using the following link:
+You can access a pipeline status badge image by using the following link:
 
 ```plaintext
 https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg
@@ -309,7 +323,7 @@ https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg
 
 #### Display only non-skipped status
 
-If you want the pipeline status badge to only display the last non-skipped status, you can use the `?ignore_skipped=true` query parameter:
+To make the pipeline status badge display only the last non-skipped status, use the `?ignore_skipped=true` query parameter:
 
 ```plaintext
 https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true
@@ -317,20 +331,20 @@ https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ig
 
 ### Test coverage report badge
 
-GitLab makes it possible to define the regular expression for the [coverage report](#test-coverage-parsing),
+You can define the regular expression for the [coverage report](#add-test-coverage-results-to-a-merge-request)
 that each job log is matched against. This means that each job in the
 pipeline can have the test coverage percentage value defined.
 
-The test coverage badge can be accessed using following link:
+To access the test coverage badge, use the following link:
 
 ```plaintext
 https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg
 ```
 
-If you would like to get the coverage report from a specific job, you can add
+To get the coverage report from a specific job, add
 the `job=coverage_job_name` parameter to the URL. For example, the following
 Markdown code embeds the test coverage report badge of the `coverage` job
-into your `README.md`:
+in your `README.md`:
 
 ```markdown
 ![coverage](https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=coverage)
diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md
index 3f52627740f..2f845a05a4e 100644
--- a/doc/ci/runners/configure_runners.md
+++ b/doc/ci/runners/configure_runners.md
@@ -19,14 +19,14 @@ Read [clearing the cache](../caching/index.md#clearing-the-cache).
 ## Set maximum job timeout for a runner
 
 For each runner, you can specify a *maximum job timeout*. This timeout,
-if smaller than the [project defined timeout](../pipelines/settings.md#timeout), takes precedence.
+if smaller than the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run), takes precedence.
 
 This feature can be used to prevent your shared runner from being overwhelmed
 by a project that has jobs with a long timeout (for example, one week).
 
 When not configured, runners do not override the project timeout.
 
-On GitLab.com, you cannot override the job timeout for shared runners and must use the [project defined timeout](../pipelines/settings.md#timeout).
+On GitLab.com, you cannot override the job timeout for shared runners and must use the [project defined timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run).
 
 To set the maximum job timeout:
 
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index 8cdcdb2d61d..26974eb4abd 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -3418,7 +3418,7 @@ test:
 ```
 
 The job-level timeout can exceed the
-[project-level timeout](../pipelines/settings.md#timeout) but can't
+[project-level timeout](../pipelines/settings.md#set-a-limit-for-how-long-jobs-can-run) but can't
 exceed the runner-specific timeout.
 
 ### `parallel`
diff --git a/doc/development/code_review.md b/doc/development/code_review.md
index 20530d805ca..a24a4ecc266 100644
--- a/doc/development/code_review.md
+++ b/doc/development/code_review.md
@@ -605,7 +605,7 @@ A merge request may benefit from being considered a customer critical priority b
 
 Properties of customer critical merge requests:
 
-- The [Senior Director of Development](https://about.gitlab.com/job-families/engineering/engineering-management/#senior-director-engineering) ([@clefelhocz1](https://gitlab.com/clefelhocz1)) is the DRI for deciding if a merge request is customer critical.
+- The [VP of Development](https://about.gitlab.com/job-families/engineering/development/management/vp) ([@clefelhocz1](https://gitlab.com/clefelhocz1)) is the DRI for deciding if a merge request qualifies as customer critical.
 - The DRI applies the `customer-critical-merge-request` label to the merge request.
 - It is required that the reviewer(s) and maintainer(s) involved with a customer critical merge request are engaged as soon as this decision is made.
 - It is required to prioritize work for those involved on a customer critical merge request so that they have the time available necessary to focus on it.
diff --git a/doc/development/database/transaction_guidelines.md b/doc/development/database/transaction_guidelines.md
new file mode 100644
index 00000000000..1c25496b153
--- /dev/null
+++ b/doc/development/database/transaction_guidelines.md
@@ -0,0 +1,117 @@
+---
+stage: Enablement
+group: Database
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Transaction guidelines
+
+This document gives a few examples of the usage of database transactions in application code.
+
+For further reference please check PostgreSQL documentation about [transactions](https://www.postgresql.org/docs/current/tutorial-transactions.html).
+
+## Database decomposition and sharding
+
+The [sharding group](https://about.gitlab.com/handbook/engineering/development/enablement/sharding) plans to split the main GitLab database and move some of the database tables to other database servers.
+
+The group will start decomposing the `ci_*` related database tables first. To maintain the current application development experience, tooling and static analyzers will be added to the codebase to ensure correct data access and data modification methods. By using the correct form for defining database transactions, we can save significant refactoring work in the future.
+
+## The transaction block
+
+The `ActiveRecord` library provides a convenient way to group database statements into a transaction.
+
+```ruby
+issue = Issue.find(10)
+project = issue.project
+
+ApplicationRecord.transaction do
+  issue.update!(title: 'updated title')
+  project.update!(last_update_at: Time.now)
+end
+```
+
+This transaction involves two database tables, in case of an error, each `UPDATE` statement will be rolled back to the previous, consistent state.
+
+NOTE:
+Avoid referencing the `ActiveRecord::Base` class and use `ApplicationRecord` instead.
+
+## Transaction and database locks
+
+When a transaction block is opened, the database will try to acquire the necessary locks on the resources. The type of locks will depend on the actual database statements.
+
+Consider a concurrent update scenario where the following code is executed at the same time from two different processes:
+
+```ruby
+issue = Issue.find(10)
+project = issue.project
+
+ApplicationRecord.transaction do
+  issue.update!(title: 'updated title')
+  project.update!(last_update_at: Time.now)
+end
+```
+
+The database will try to acquire the `FOR UPDATE` lock for the referenced `issue` and `project` records. In our case, we have two competing transactions for these locks, one of them will successfully acquire them. The other transaction will have to wait in the lock queue until the first transaction finishes. The execution of the second transaction is blocked at this point.
+
+## Transaction speed
+
+To prevent lock contention and maintain stable application performance, the transaction block should finish as fast as possible. When a transaction acquires locks, it will hold on to them until the transaction finishes.
+
+Apart from application performance, long-running transactions can also affect the application upgrade processes by blocking database migrations.
+
+### Dangerous example: 3rd party API calls
+
+Consider the following example:
+
+```ruby
+member = Member.find(5)
+
+Member.transaction do
+  member.update!(notification_email_sent: true)
+
+  member.send_notification_email
+end
+```
+
+Here, we ensure that the `notification_email_sent` column is updated only when the `send_notification_email` method succeeds. The `send_notification_email` method executes a network request to an email sending service. If the underlying infrastructure does not specify timeouts or the network call takes too long time, the database transaction will stay open.
+
+Ideally, a transaction should only contain database statements.
+
+Avoid doing in a `transaction` block:
+
+- External network requests such as: triggering Sidekiq jobs, sending emails, HTTP API calls and running database statements using a different connection.
+- File system operations.
+- Long, CPU intensive computation.
+- Calling `sleep(n)`.
+
+## Explicit model referencing
+
+If a transaction modifies records from the same database table, it's advised to use the `Model.transaction` block:
+
+```ruby
+build_1 = Ci::Build.find(1)
+build_2 = Ci::Build.find(2)
+
+Ci::Build.transaction do
+  build_1.touch
+  build_2.touch
+end
+```
+
+The transaction above will use the same database connection for the transaction as the models in the `transaction` block. In a multi-database environment the following example would be dangerous:
+
+```ruby
+# `ci_builds` table is located on another database
+class Ci::Build < CiDatabase
+end
+
+build_1 = Ci::Build.find(1)
+build_2 = Ci::Build.find(2)
+
+ActiveRecord::Base.transaction do
+  build_1.touch
+  build_2.touch
+end
+```
+
+The `ActiveRecord::Base` class uses a different database connection than the `Ci::Build` records. The two statements in the transaction block will not be part of the transaction and will not be rolled back in case something goes wrong. They act as 3rd part calls.
diff --git a/doc/subscriptions/gitlab_com/index.md b/doc/subscriptions/gitlab_com/index.md
index 38347172958..32f587d900e 100644
--- a/doc/subscriptions/gitlab_com/index.md
+++ b/doc/subscriptions/gitlab_com/index.md
@@ -272,14 +272,15 @@ If you add a member to a group by using the [share a group with another group](.
 
 ## CI pipeline minutes
 
-CI pipeline minutes are the execution time for your
-[pipelines](../../ci/pipelines/index.md) on GitLab shared runners. Each
-[GitLab SaaS tier](https://about.gitlab.com/pricing/) includes a monthly quota
-of CI pipeline minutes:
-
-- Free: 400 minutes
-- Premium: 10,000 minutes
-- Ultimate: 50,000 minutes
+CI pipeline minutes are the execution time for your [pipelines](../../ci/pipelines/index.md)
+on GitLab shared runners. Each [GitLab SaaS tier](https://about.gitlab.com/pricing/)
+includes a monthly quota of CI pipeline minutes for private and public projects:
+
+| Plan     | Private projects | Public projects |
+|----------|------------------|-----------------|
+| Free     | 400              | 50,000          |
+| Premium  | 10,000           | 1,250,000       |
+| Ultimate | 50,000           | 6,250,000       |
 
 Quotas apply to:
 
diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v13_2.png b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v13_2.png
deleted file mode 100644
index ee3bb310c1a..00000000000
--- a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v13_2.png
+++ /dev/null
diff --git a/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png
new file mode 100644
index 00000000000..c188c6cd834
--- /dev/null
+++ b/doc/user/compliance/license_compliance/img/policies_maintainer_edit_v14_2.png
diff --git a/doc/user/compliance/license_compliance/index.md b/doc/user/compliance/license_compliance/index.md
index e67a0d9c3cb..1a43c5ae96f 100644
--- a/doc/user/compliance/license_compliance/index.md
+++ b/doc/user/compliance/license_compliance/index.md
@@ -47,8 +47,7 @@ When GitLab detects a **Denied** license, you can view it in the [license list](
 ![License List](img/license_list_v13_0.png)
 
 You can view and modify existing policies from the [policies](#policies) tab.
-
-![Edit Policy](img/policies_maintainer_edit_v13_2.png)
+![Edit Policy](img/policies_maintainer_edit_v14_2.png)
 
 ## Supported languages and package managers
 
@@ -722,7 +721,7 @@ which enables a designated approver that can approve and then merge a merge requ
 The **Policies** tab in the project's license compliance section displays your project's license
 policies. Project maintainers can specify policies in this section.
 
-![Edit Policy](img/policies_maintainer_edit_v13_2.png)
+![Edit Policy](img/policies_maintainer_edit_v14_2.png)
 ![Add Policy](img/policies_maintainer_add_v13_2.png)
 
 Developers of the project can view the policies configured in a project.
diff --git a/doc/user/group/repositories_analytics/index.md b/doc/user/group/repositories_analytics/index.md
index b9f94d96b48..054c6ab7a6b 100644
--- a/doc/user/group/repositories_analytics/index.md
+++ b/doc/user/group/repositories_analytics/index.md
@@ -41,7 +41,7 @@ To see the latest code coverage for each project in your group:
 1. In the **Latest test coverage results** section, use the **Select projects** dropdown to choose the projects you want to check.
 
 You can download code coverage data for specific projects using
-[code coverage history](../../../ci/pipelines/settings.md#code-coverage-history).
+[code coverage history](../../../ci/pipelines/settings.md#view-code-coverage-history).
 
 ## Download historic test coverage data