Add latest changes from gitlab-org/gitlab@master

9 files changed, 156 insertions, 64 deletions

diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md
index fa668091c90..f794ea6745f 100644
--- a/doc/administration/geo/replication/troubleshooting.md
+++ b/doc/administration/geo/replication/troubleshooting.md
@@ -204,7 +204,7 @@ Commands that change data can cause damage if not run correctly or under the rig
    ```
 
 1. This will cause the primary to start checksumming all Uploads.
-1. When a primary successfully checksums a record, then all secondaries rechecksum as well, and they compare the values.
+1. When a primary successfully checksums a record, then all secondaries recalculate the checksum as well, and they compare the values.
 
 A similar thing can be done for all Models handled by the [Geo Self-Service Framework](../../../development/geo/framework.md) which have implemented verification:
 
@@ -1335,7 +1335,7 @@ status
    ```
 
 1. This will cause the primary to start checksumming all Uploads.
-1. When a primary successfully checksums a record, then all secondaries rechecksum as well, and they compare the values.
+1. When a primary successfully checksums a record, then all secondaries recalculate the checksum as well, and they compare the values.
 
 For other SSF data types replace `Upload` in the command above with the desired model class.
 
diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md
index 93b2e33e11c..a000fd0fbd0 100644
--- a/doc/development/documentation/styleguide/index.md
+++ b/doc/development/documentation/styleguide/index.md
@@ -345,6 +345,19 @@ Some contractions, however, should be avoided:
 
 <!-- vale gitlab.Possessive = YES -->
 
+### Prepositions
+
+Use prepositions at the end of the sentence when needed.
+Dangling or stranded prepositions are fine. For example:
+
+- You can leave the group you're a member of.
+- Share the credentials with users you want to give access to.
+
+These constructions are more casual than the alternatives:
+
+- You can leave the group of which you're a member.
+- Share the credentials with users to which you want to give access.
+
 ### Acronyms
 
 If you use an acronym, spell it out on first use on a page. You do not need to spell it out more than once on a page.
diff --git a/doc/development/documentation/styleguide/word_list.md b/doc/development/documentation/styleguide/word_list.md
index 09240e63617..1a012051960 100644
--- a/doc/development/documentation/styleguide/word_list.md
+++ b/doc/development/documentation/styleguide/word_list.md
@@ -1177,6 +1177,11 @@ Always follow these words with a noun. For example:
 - Use: **Those settings** need to be configured. (Or even better, **Configure those settings.**)
 - Instead of: **Those** need to be configured.
 
+## to which, of which
+
+Try to avoid **to which** and **of which**, and let the preposition dangle at the end of the sentence instead.
+For examples, see [Prepositions](index.md#prepositions).
+
 ## to-do item
 
 Use lowercase and hyphenate **to-do** item. ([Vale](../testing.md#vale) rule: [`ToDo.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/ToDo.yml))
diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md
index 3d3fe35fd65..dd6605c2f01 100644
--- a/doc/user/packages/conan_repository/index.md
+++ b/doc/user/packages/conan_repository/index.md
@@ -270,8 +270,9 @@ Prerequisites:
    ```
 
 NOTE:
-If you try to install the package you just created in this tutorial, the package
-already exists on your local computer, so this command has no effect.
+If you try installing the package you created in this tutorial, the install command
+will have no effect because the package already exists.
+Delete `~/.conan/data` to clean up the packages stored in the cache.
 
 ## Remove a Conan package
 
diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md
index 296bb9ece39..f71a9030630 100644
--- a/doc/user/packages/container_registry/index.md
+++ b/doc/user/packages/container_registry/index.md
@@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > Searching by image repository name was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31322) in GitLab 13.0.
 
 NOTE:
-If you pull container images from Docker Hub, you can use the [GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images) 
+If you pull container images from Docker Hub, you can use the [GitLab Dependency Proxy](../dependency_proxy/index.md#use-the-dependency-proxy-for-docker-images)
 to avoid rate limits and speed up your pipelines.
 
 With the Docker Container Registry integrated into GitLab, every GitLab project can
@@ -32,6 +32,7 @@ You can search, sort, filter, and [delete](#delete-images-using-the-gitlab-ui)
 containers on this page. You can share a filtered view by copying the URL from your browser.
 
 Only members of the project or group can access a private project's Container Registry.
+Images downloaded from a private registry may be [available to other users in a shared runner](https://docs.gitlab.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy).
 
 If a project is public, so is the Container Registry.
 
diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md
index 8e160cbb195..65ff715a4ee 100644
--- a/doc/user/packages/package_registry/index.md
+++ b/doc/user/packages/package_registry/index.md
@@ -118,18 +118,22 @@ determine actions such as downloading, pushing, or deleting packages.
 
 The visibility of the Package Registry is independent of the repository and can't be controlled from
 your project's settings. For example, if you have a public project and set the repository visibility
-to **Only Project Members**, the Package Registry is then public. However, disabling the Package
+to **Only Project Members**, the Package Registry is then public. Disabling the Package
 Registry disables all Package Registry operations.
 
-[GitLab-#329253](https://gitlab.com/gitlab-org/gitlab/-/issues/329253)
-proposes adding the ability to control Package Registry visibility from the UI.
-
-|                      |                       | Anonymous<br/>(everyone on internet) | Guest | Reporter, Developer, Maintainer, Owner |
-| -------------------- | --------------------- | --------- | ----- | ------------------------------------------ |
-| Public project with Package Registry enabled | View Package Registry <br/> and pull packages | Yes       | Yes   | Yes      |
-| Internal project with Package Registry enabled | View Package Registry <br/> and pull packages | No       | Yes   | Yes      |
-| Private project with Package Registry enabled | View Package Registry <br/> and pull packages | No        | No    | Yes      |
-| Any project with Package Registry disabled | All operations on Package Registry | No | No | No |
+| Project visibility | Action | [Role](../../permissions.md#roles) required |
+| ---- | ---- | ---- |
+| Public | View Package Registry | `n/a`, everyone on the internet can perform this action |
+| Public | Publish a package | Developer or higher |
+| Public | Pull a package | `n/a`, everyone on the internet can perform this action |
+| Internal | View Package Registry | Guest or higher |
+| Internal | Publish a package | Developer or higher |
+| Internal | Pull a package | Guest or higher(1) |
+| Private | View Package Registry | Reporter or higher |
+| Private | Publish a package | Developer or higher |
+| Private | Pull a package | Reporter or higher(1) |
+
+1. [GitLab-#329253](https://gitlab.com/gitlab-org/gitlab/-/issues/329253) proposes adding a setting to allow anyone (everyone on the internet) to pull from the Package Registry, no matter what the project visibility is.
 
 ## Supported package managers
 
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 3c9f1544158..d70a1a4ba1d 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -342,7 +342,7 @@ This table shows granted privileges for jobs triggered by specific types of user
 | Push source and LFS                          |                 |           |            |               |
 
 1. Only if the triggering user is not an external one.
-1. Only if the triggering user is a member of the project.
+1. Only if the triggering user is a member of the project. See also [Usage of private Docker images with `if-not-present` pull policy](http://docs.gitlabl.com/runner/security/index.html#usage-of-private-docker-images-with-if-not-present-pull-policy).
 
 ### Wiki and issues
 
diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md
index a2a12b22c3b..a8acab3898b 100644
--- a/doc/user/project/merge_requests/approvals/settings.md
+++ b/doc/user/project/merge_requests/approvals/settings.md
@@ -21,22 +21,24 @@ To view or edit merge request approval settings:
 
 ### Approval settings
 
-These settings limit who can approve merge requests.
-
-| Setting | Description |
-| ------ | ------ |
-| [Prevent approval by author](#prevent-approval-by-author)  | When enabled, the author of a merge request cannot approve it. |
-| [Prevent approvals by users who add commits](#prevent-approvals-by-users-who-add-commits) | When enabled, users who have committed to a merge request cannot approve it. |
-| [Prevent editing approval rules in merge requests](#prevent-editing-approval-rules-in-merge-requests) | When enabled, users can't override the project's approval rules on merge requests.  |
-| [Require user password to approve](#require-user-password-to-approve) | Force potential approvers to first authenticate with a password. |
-
-You can further define what happens to existing approvals when commits are added to the merge request.
-
-| Setting | Description |
-| ------ | ------ |
-| Keep approvals | Do not remove approvals. |
-| [Remove all approvals](#remove-all-approvals-when-commits-are-added-to-the-source-branch) | Remove all existing approvals. |
-| [Remove approvals by Code Owners if their files changed](#remove-approvals-by-code-owners-if-their-files-changed) | If a Code Owner has approved the merge request, and the commit changes files they are the Code Owner for, their approval is removed. |
+These settings limit who can approve merge requests:
+
+- [**Prevent approval by author**](#prevent-approval-by-author):
+  Prevents the author of a merge request from approving it.
+- [**Prevent approvals by users who add commits**](#prevent-approvals-by-users-who-add-commits):
+  Prevents users who add commits to a merge request from also approving it.
+- [**Prevent editing approval rules in merge requests**](#prevent-editing-approval-rules-in-merge-requests):
+  Prevents users from overriding project level approval rules on merge requests.
+- [**Require user password to approve**](#require-user-password-to-approve):
+  Force potential approvers to first authenticate with a password.
+- Code Owner approval removals: Define what happens to existing approvals when
+  commits are added to the merge request.
+  - **Keep approvals**: Do not remove any approvals.
+  - [**Remove all approvals**](#remove-all-approvals-when-commits-are-added-to-the-source-branch):
+    Remove all existing approvals.
+  - [**Remove approvals by Code Owners if their files changed**](#remove-approvals-by-code-owners-if-their-files-changed):
+    If a Code Owner approves a merge request, and a later commit changes files
+    they are a Code Owner for, their approval is removed.
 
 ## Prevent approval by author
 
diff --git a/doc/user/project/merge_requests/methods/index.md b/doc/user/project/merge_requests/methods/index.md
index e72c927198e..249a98f1779 100644
--- a/doc/user/project/merge_requests/methods/index.md
+++ b/doc/user/project/merge_requests/methods/index.md
@@ -10,47 +10,107 @@ type: reference, concepts
 The merge method you select for your project determines how the changes in your
 merge requests are merged into an existing branch.
 
+The examples on this page assume a `main` branch with commits A, C, and E, and a
+`feature` branch with commits B and D:
+
+```mermaid
+gitGraph
+   commit id: "A"
+   branch feature
+   commit id: "B"
+   commit id: "D"
+   checkout main
+   commit id: "C"
+   commit id: "E"
+```
+
 ## Configure a project's merge method
 
 1. On the top bar, select **Main menu > Projects** and find your project.
 1. On the left sidebar, select **Settings > Merge requests**.
-1. In the **Merge method** section, select your desired merge method.
+1. Select your desired **Merge method** from these options:
+   - Merge commit
+   - Merge commit with semi-linear history
+   - Fast-forward merge
+1. In **Squash commits when merging**, select the default behavior for handling commits:
+   - **Do not allow**: Squashing is never performed, and the user cannot change the behavior.
+   - **Allow**: Squashing is off by default, but the user can change the behavior.
+   - **Encourage**: Squashing is on by default, but the user can change the behavior.
+   - **Require**: Squashing is always performed, and the user cannot change the behavior.
 1. Select **Save changes**.
 
 ## Merge commit
 
-This setting is the default. It always creates a separate merge commit,
-even when using [squash](../squash_and_merge.md). An example commit graph generated using this merge method:
+By default, GitLab creates a merge commit when a branch is merged into `main`.
+A separate merge commit is always created, regardless of whether or not commits
+are [squashed when merging](../squash_and_merge.md). This strategy can result
+in both a squash commit and a merge commit being added to your `main` branch.
+
+These diagrams show how the `feature` branch merges into `main` if you use the
+**Merge commit** strategy. They are equivalent to the command `git merge --no-ff <feature>`,
+and selecting `Merge commit` as the **Merge method** in the GitLab UI:
+
+The merge strategy:
 
 ```mermaid
+%%{init: { 'gitGraph': {'logLevel': 'debug', 'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'main'}} }%%
 gitGraph
-  commit id: "Init"
-  branch mr-branch-1
-  commit
-  checkout main
-  commit
-  branch mr-branch-2
-  commit
-  checkout mr-branch-1
-  commit
-  checkout main
-  branch squash-mr
-  commit id: "Squashed commits"
-  checkout main
-  merge squash-mr
-  merge mr-branch-1
-  commit
-  merge mr-branch-2
+   commit id: "A"
+   branch feature
+   commit id: "B"
+   commit id: "D"
+   checkout main
+   commit id: "C"
+   commit id: "E"
+   merge feature
+```
+
+After a feature branch is merged with the **Merge commit** method, your `main` branch
+looks like this:
+
+```mermaid
+%%{init: { 'gitGraph': {'logLevel': 'debug', 'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'main'}} }%%
+gitGraph
+   commit id: "A"
+   commit id: "C"
+   commit id: "E"
+   commit id: "squash commit"
+   commit id: "merge commit"
 ```
 
-- For regular merges, it is equivalent to the command `git merge --no-ff <source-branch>`.
-- For squash merges, it squashes all commits in the source branch before merging it normally. It performs actions similar to:
+In comparison, a **squash merge** constructs a squash commit, a virtual copy of all commits
+from the `feature` branch. The original commits (B and D) remain unchanged
+on the `feature` branch, and the squash commit is placed on the `main` branch:
+
+```mermaid
+%%{init: { 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchName': 'main'}} }%%
+gitGraph
+   commit id:"A"
+   branch feature
+   checkout main
+   commit id:"C"
+   checkout feature
+   commit id:"B"
+   commit id:"D"
+   checkout main
+   commit id:"E"
+   commit id:"squash commit" type: HIGHLIGHT
+```
+
+The squash merge graph is equivalent to these settings in the GitLab UI:
+
+- **Merge method**: Merge commit.
+- **Squash commits when merging** should be set to either:
+  - Require.
+  - Either Allow or Encourage, and squashing must be selected on the merge request.
+
+The squash merge graph is also equivalent to these commands:
 
   ```shell
-  git checkout `git merge-base <source-branch> <target-branch>`
-  git merge --squash <source-branch>
+  git checkout `git merge-base feature main`
+  git merge --squash <feature>
   SOURCE_SHA=`git rev-parse HEAD`
-  git checkout <target-branch>
+  git checkout <main>
   git merge --no-ff $SOURCE_SHA
   ```
 
@@ -58,7 +118,8 @@ gitGraph
 
 A merge commit is created for every merge, but the branch is only merged if
 a fast-forward merge is possible. This ensures that if the merge request build
-succeeded, the target branch build also succeeds after the merge. An example commit graph generated using this merge method:
+succeeded, the target branch build also succeeds after the merge. An example
+commit graph generated using this merge method:
 
 ```mermaid
 gitGraph
@@ -113,8 +174,8 @@ This method is equivalent to `git merge --ff <source-branch>` for regular merges
 
 When the fast-forward merge
 ([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting
-is enabled, no merge commits are created and all merges are fast-forwarded,
-which means that merging is only allowed if the branch can be fast-forwarded.
+is enabled, no merge commits are created and all merges are fast-forwarded.
+Merging is only allowed if the branch can be fast-forwarded.
 When a fast-forward merge is not possible, the user is given the option to rebase, see
 [Rebasing in (semi-)linear merge methods](#rebasing-in-semi-linear-merge-methods).
 
@@ -136,11 +197,16 @@ In these merge methods, you can merge only when your source branch is up-to-date
 - Fast-forward merge.
 
 If a fast-forward merge is not possible but a conflict-free rebase is possible,
-GitLab offers you the [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui),
-and the ability to select **Rebase** from the user interface.
+GitLab provides:
+
+- The [`/rebase` quick action](../../../../topics/git/git_rebase.md#rebase-from-the-gitlab-ui).
+- The option to select **Rebase** in the user interface.
+
+You must rebase the source branch locally before a fast-forward merge if both
+conditions are true:
 
-If the target branch is ahead of the source branch and a conflict-free rebase is
-not possible, you must rebase the source branch locally before you can do a fast-forward merge.
+- The target branch is ahead of the source branch.
+- A conflict-free rebase is not possible.
 
 ![Fast forward merge rebase locally](../img/ff_merge_rebase_locally.png)