Merge branch 'docs-aqualls-create-3' into 'master'

Word and line reviews for Create documentation See merge request gitlab-org/gitlab!52852

Merge branch 'docs-aqualls-create-3' into 'master'
Word and line reviews for Create documentation See merge request gitlab-org/gitlab!52852
1950c267 · Craig Norris · a56d6581 · 781109b5 · 1950c267 · 1950c267
Commit 1950c267 authored Jan 29, 2021 by Craig Norris
5 changed files
--- a/doc/user/project/code_owners.md
+++ b/doc/user/project/code_owners.md
@@ -7,9 +7,8 @@ type: reference
 # Code Owners **(STARTER)**
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916)
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3.
-in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
+> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9.
-> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9.
 ## Introduction
@@ -18,7 +17,7 @@ to find out who should review or approve merge requests.
 Additionally, if you have a question over a specific file or
 code block, it may be difficult to know who to find the answer from.
-GitLab Code Owners is a feature to define who owns specific
+The GitLab Code Owners feature defines who owns specific
 files or paths in a repository, allowing other users to understand
 who is responsible for each file or path.
@@ -32,7 +31,7 @@ the process of finding the right reviewers and approvers for a given
 merge request.
 In larger organizations or popular open source projects, Code Owners
-can also be useful to understand who to contact if you have
+can help you understand who to contact if you have
 a question that may not be related to code review or a merge request
 approval.
@@ -49,12 +48,12 @@ You can choose to add the `CODEOWNERS` file in three places:
 - Inside the `docs/` directory
 The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners
-in a feature branch, they won't be valid in the main branch until the feature branch is merged.
+in a feature branch, the changes aren't valid in the main branch until the feature branch is merged.
 If you introduce new files to your repository and you want to identify the code owners for that file,
-you have to update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same
+you must update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same
-branch), GitLab will count the owners as soon as the branch is merged. If
+branch), GitLab counts the owners as soon as the branch is merged. If
-you don't, you can do that later, but your new files will not belong to anyone until you update your
+you don't, you can do that later, but your new files don't belong to anyone until you update your
 `CODEOWNERS` file in the TARGET branch.
 When a file matches multiple entries in the `CODEOWNERS` file,
@@ -73,29 +72,32 @@ The user that would show for `README.md` would be `@user2`.
 ## Approvals by Code Owners
-Once you've added Code Owners to a project, you can configure it to
+After you've added Code Owners to a project, you can configure it to
 be used for merge request approvals:
 - As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers).
 - As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)**
-Developer or higher [permissions](../permissions.md) are required in order to
+Developer or higher [permissions](../permissions.md) are required to
 approve a merge request.
-Once set, Code Owners are displayed in merge requests widgets:
+After it's set, Code Owners are displayed in merge request widgets:
 ![MR widget - Code Owners](img/code_owners_mr_widget_v12_4.png)
-While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules),
+While you can use the `CODEOWNERS` file in addition to Merge Request
-it can also be used as the sole driver of merge request approvals
+[Approval Rules](merge_requests/merge_request_approvals.md#approval-rules),
-(without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)).
+you can also use it as the sole driver of merge request approvals
-To do so, create the file in one of the three locations specified above and
+without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules):
-set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners).
-Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files)
+1. Create the file in one of the three locations specified above.
-to specify the actual owners and granular permissions.
+1. Set the code owners as required approvers for
+   [protected branches](protected_branches.md#protected-branches-approval-by-code-owners).
+1. Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files)
+   to specify the actual owners and granular permissions.
 Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners)
-will prevent any user who is not specified in the `CODEOWNERS` file from pushing
+prevents any user who is not specified in the `CODEOWNERS` file from pushing
 changes for the specified files/paths, except those included in the
 **Allowed to push** column. This allows for a more inclusive push strategy, as
 administrators don't have to restrict developers from pushing directly to the
@@ -114,13 +116,13 @@ in the `.gitignore` file followed by one or more of:
 - The `@name` of one or more groups that should be owners of the file.
 - Lines starting with `#` are ignored.
-The order in which the paths are defined is significant: the last pattern that
+The path definition order is significant: the last pattern
-matches a given path will be used to find the code owners.
+matching a given path is used to find the code owners.
 ### Groups as Code Owners
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab Starter 12.1.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1.
-> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0.
+> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0.
 Groups and subgroups members are inherited as eligible Code Owners to a
 project, as long as the hierarchy is respected.
@@ -131,7 +133,7 @@ suppose you have a project called "Project A" within the group and a
 "Project B" within the subgroup.
 The eligible Code Owners to Project B are both the members of the Group X and
-the Subgroup Y. And the eligible Code Owners to the Project A are just the
+the Subgroup Y. The eligible Code Owners to the Project A are just the
 members of the Group X, given that Project A doesn't belong to the Subgroup Y:
 ![Eligible Code Owners](img/code_owners_members_v13_4.png)
@@ -142,9 +144,9 @@ Code Owners:
 ![Invite subgroup members to become eligible Code Owners](img/code_owners_invite_members_v13_4.png)
-Once invited, any member (`@user`) of the group or subgroup can be set
+After being invited, any member (`@user`) of the group or subgroup can be set
-as Code Owner to files of the Project A or B, as well as the entire Group X
+as Code Owner to files of the Project A or B, and the entire Group X
-(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as exemplified below:
+(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as follows:
 ```plaintext
 # A member of the group or subgroup as Code Owner to a file
@@ -162,7 +164,7 @@ file.md @group-x @group-x/subgroup-y
 ### Code Owners Sections **(PREMIUM)**
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2 behind a feature flag, enabled by default.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab Premium 13.2 behind a feature flag, enabled by default.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4.
 Code Owner rules can be grouped into named sections. This allows for better
@@ -185,8 +187,8 @@ changes, to set their own independent patterns by specifying discrete sections i
 teams can be added as reviewers.
 Sections can be added to `CODEOWNERS` files as a new line with the name of the
-section inside square brackets. Every entry following it is assigned to that
+section inside square brackets. Every entry following is assigned to that
-section. The following example would create 2 Code Owner rules for the "README
+section. The following example would create two Code Owner rules for the "README
 Owners" section:
 ```plaintext
@@ -196,7 +198,7 @@ internal/README.md @user2
 ```
 Multiple sections can be used, even with matching file or directory patterns.
-Reusing the same section name will group the results together under the same
+Reusing the same section name groups the results together under the same
 section, with the most specific rule or last matching pattern being used. For
 example, consider the following entries in a `CODEOWNERS` file:
@@ -213,7 +215,7 @@ model/db   @gl-database
 README.md  @gl-docs
 ```
-This will result in 3 entries under the "Documentation" section header, and 2
+This results in three entries under the "Documentation" section header, and two
 entries under "Database". Case is not considered when combining sections, so in
 this example, entries defined under the sections "Documentation" and
 "DOCUMENTATION" would be combined into one, using the case of the first instance
@@ -227,9 +229,10 @@ the rules for "Groups" and "Documentation" sections:
 #### Optional Code Owners Sections **(PREMIUM)**
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.8 behind a feature flag, enabled by default.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default.
-When you want to make a certain section optional, you can do so by adding a code owners section prepended with the caret `^` character. Approvals from owners listed in the section will **not** be required. For example:
+To make a certain section optional, add a code owners section prepended with the
+caret `^` character. Approvals from owners listed in the section are **not** required. For example:
 ```plaintext
 [Documentation]
@@ -242,13 +245,13 @@ When you want to make a certain section optional, you can do so by adding a code
 *.go @root
 ```
-The optional code owners section will be displayed in merge requests under the **Approval Rules** area:
+The optional code owners section displays in merge requests under the **Approval Rules** area:
 ![MR widget - Optional Code Owners Sections](img/optional_code_owners_sections_v13_8.png)
-If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails. 
+If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails.
-For example, the code owners of the "Documentation" section below will still be required to approve merge requests: 
+For example, the code owners of the "Documentation" section below is still required to approve merge requests:
 ```plaintext
 [Documentation]
@@ -264,12 +267,12 @@ For example, the code owners of the "Documentation" section below will still be
 *.txt @root
 ```
-Optional sections in the code owners file are currently treated as optional only
+Optional sections in the code owners file are treated as optional only
-when changes are submitted via merge requests. If a change is submitted directly
+when changes are submitted by using merge requests. If a change is submitted directly
-to the protected branch, approval from code owners will still be required, even if the
+to the protected branch, approval from code owners is still required, even if the
-section is marked as optional. We plan to change this in a
+section is marked as optional. We plan to change this behavior in a
 [future release](https://gitlab.com/gitlab-org/gitlab/-/issues/297638),
-where direct pushes to the protected branch will be allowed for sections marked as optional.
+and allow direct pushes to the protected branch for sections marked as optional.
 ## Example `CODEOWNERS` file

--- a/doc/user/project/highlighting.md
+++ b/doc/user/project/highlighting.md
@@ -7,7 +7,7 @@ type: reference
 # Syntax Highlighting
-GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It will try to guess what language to use based on the file extension, which most of the time is sufficient.
+GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient.
 NOTE:
 The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/)
@@ -25,10 +25,10 @@ you can add the following to your `.gitattributes` file:
 ```
 <!-- vale gitlab.Spelling = NO -->
-When you check in and push that change, all `*.pl` files in your project will be highlighted as Prolog.
+When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog.
 <!-- vale gitlab.Spelling = YES -->
-The paths here are simply Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is:
+The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is:
 ``` conf
 /Nicefile gitlab-language=ruby
@@ -44,7 +44,8 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen
 /other-file gitlab-language=text?token=Error
 ```
-Please note that these configurations will only take effect when the `.gitattributes` file is in your default branch (usually `master`).
+Please note that these configurations only take effect when the `.gitattributes`
+file is in your default branch (usually `master`).
 NOTE:
 The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014).
--- a/doc/user/project/index.md
+++ b/doc/user/project/index.md
@@ -17,12 +17,12 @@ the number of private projects you create.
 ## Project features
-When you create a project in GitLab, you'll have access to a large number of
+When you create a project in GitLab, you receive access to a large number of
 [features](https://about.gitlab.com/features/):
 **Repositories:**
- [Issue tracker](issues/index.md): Discuss implementations with your team within issues
+- [Issue tracker](issues/index.md): Discuss implementations with your team in issues
  - [Issue Boards](issue_board.md): Organize and prioritize your workflow
  - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project
 - [Repositories](repository/index.md): Host your code in a fully
@@ -42,13 +42,13 @@ When you create a project in GitLab, you'll have access to a large number of
 **Issues and merge requests:**
- [Issue tracker](issues/index.md): Discuss implementations with your team within issues
+- [Issue tracker](issues/index.md): Discuss implementations with your team in issues
  - [Issue Boards](issue_board.md): Organize and prioritize your workflow
  - [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project
 - [Merge Requests](merge_requests/index.md): Apply your branching
  strategy and get reviewed by your team
  - [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before
-  implementing a change **(STARTER)**
+  implementing a change
  - [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md):
  Your Git diff tool right from the GitLab UI
  - [Review Apps](../../ci/review_apps/index.md): Live preview the results
@@ -108,7 +108,7 @@ When you create a project in GitLab, you'll have access to a large number of
 - [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab.
 - [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab.
 - [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab.
- [Code owners](code_owners.md): specify code owners for certain files **(STARTER)**
+- [Code owners](code_owners.md): specify code owners for certain files
 - [License Compliance](../compliance/license_compliance/index.md): approve and deny licenses for projects. **(ULTIMATE)**
 - [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)**
 - [Requirements](requirements/index.md): Requirements allow you to create criteria to check your products against. **(ULTIMATE)**
@@ -192,7 +192,7 @@ To delete a project, first navigate to the home page for that project.
 1. Click **Delete project**
 1. Confirm this action by typing in the expected text.
-Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects within a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal).
+Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal).
 ## CI/CD for external repositories **(PREMIUM)**
@@ -214,11 +214,11 @@ filtered by **Push events**, **Merge events**, **Issue events**, **Comments**,
 ### Leave a project
-**Leave project** will only display on the project's dashboard
+**Leave project** only displays on the project's dashboard
 when a project is part of a group (under a
 [group namespace](../group/index.md#namespaces)).
-If you choose to leave a project you will no longer be a project
+If you choose to leave a project you are no longer a project
-member, therefore, unable to contribute.
+member, and cannot contribute.
 ## Project's landing page
@@ -230,15 +230,15 @@ with [permissions to view the project's code](../permissions.md#project-members-
 - The content of a
  [`README` or an index file](repository/#repository-readme-and-index-files)
-  is displayed (if any), followed by the list of directories within the
+  is displayed (if any), followed by the list of directories in the
  project's repository.
 - If the project doesn't contain either of these files, the
-  visitor will see the list of files and directories of the repository.
+  visitor sees the list of files and directories of the repository.
-For users without permissions to view the project's code:
+For users without permissions to view the project's code, GitLab displays:
- The wiki homepage is displayed, if any.
+- The wiki homepage, if any.
- The list of issues within the project is displayed.
+- The list of issues in the project.
 ## GitLab Workflow - VS Code extension
@@ -259,15 +259,15 @@ Depending on the situation, different things apply.
 When [renaming a user](../profile/index.md#changing-your-username),
 [changing a group path](../group/index.md#changing-a-groups-path) or [renaming a repository](settings/index.md#renaming-a-repository):
- Existing web URLs for the namespace and anything under it (e.g., projects) will
+- Existing web URLs for the namespace and anything under it (such as projects) will
  redirect to the new URLs.
 - Starting with GitLab 10.3, existing Git remote URLs for projects under the
-  namespace will redirect to the new remote URL. Every time you push/pull to a
+  namespace redirect to the new remote URL. Every time you push/pull to a
  repository that has changed its location, a warning message to update
-  your remote will be displayed instead of rejecting your action.
+  your remote is displayed instead of rejecting your action.
-  This means that any automation scripts, or Git clients will continue to
+  This means that any automation scripts, or Git clients continue to
  work after a rename, making any transition a lot smoother.
- The redirects will be available as long as the original path is not claimed by
+- The redirects are available as long as the original path is not claimed by
  another group, user or project.
 ## Use your project as a Go package
@@ -278,11 +278,11 @@ and `godoc.org` discovery requests, including the
 [`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags.
 Private projects, including projects in subgroups, can be used as a Go package,
-but may require configuration to work correctly. GitLab will respond correctly
+but may require configuration to work correctly. GitLab responds correctly
 to `go get` discovery requests for projects that *are not* in subgroups,
 regardless of authentication or authorization.
 [Authentication](#authenticate-go-requests) is required to use a private project
-in a subgroup as a Go package. Otherwise, GitLab will truncate the path for
+in a subgroup as a Go package. Otherwise, GitLab truncates the path for
 private projects in subgroups to the first two segments, causing `go get` to
 fail.
@@ -302,10 +302,10 @@ queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching)
 `GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go
 modules and Go module prefixes. For example,
-`GOPRIVATE=gitlab.example.com/my/private/project` will disable queries for that
+`GOPRIVATE=gitlab.example.com/my/private/project` disables queries for that
-one project, but `GOPRIVATE=gitlab.example.com` will disable queries for *all*
+one project, but `GOPRIVATE=gitlab.example.com` disables queries for *all*
-projects on GitLab.com. Go will not query module proxies if the module name or a
+projects on GitLab.com. Go does not query module proxies if the module name or a
-prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go will not query checksum
+prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go does not query checksum
 databases if the module name or a prefix of it appears in `GONOPRIVATE` or
 `GONOSUMDB`.
@@ -315,8 +315,8 @@ To authenticate requests to private projects made by Go, use a [`.netrc`
 file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access
 token](../profile/personal_access_tokens.md) in the password field. **This only
 works if your GitLab instance can be accessed with HTTPS.** The `go` command
-will not transmit credentials over insecure connections. This will authenticate
+does not transmit credentials over insecure connections. This authenticates
-all HTTPS requests made directly by Go but will not authenticate requests made
+all HTTPS requests made directly by Go, but does not authenticate requests made
 through Git.
 For example:
@@ -332,16 +332,18 @@ On Windows, Go reads `~/_netrc` instead of `~/.netrc`.
 ### Authenticate Git fetches
-If a module cannot be fetched from a proxy, Go will fall back to using Git (for
+If a module cannot be fetched from a proxy, Go falls back to using Git (for
-GitLab projects). Git will use `.netrc` to authenticate requests. Alternatively,
+GitLab projects). Git uses `.netrc` to authenticate requests. You can also
-Git can be configured to embed specific credentials in the request URL, or to
+configure Git to either:
-use SSH instead of HTTPS (as Go always uses HTTPS to fetch Git repositories):
+- Embed specific credentials in the request URL.
+- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories.
 ```shell
-# embed credentials in any request to GitLab.com:
+# Embed credentials in any request to GitLab.com:
 git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com"
-# use SSH instead of HTTPS:
+# Use SSH instead of HTTPS:
 git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com"
 ```
@@ -354,7 +356,7 @@ visit the `/projects/:id` URL in your browser or other tool accessing the projec
 ## Project aliases **(PREMIUM SELF)**
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1.
 When migrating repositories to GitLab and they are being accessed by other systems,
 it's very useful to be able to access them using the same name especially when
@@ -369,9 +371,9 @@ A project alias can be only created via API and only by GitLab administrators.
 Follow the [Project Aliases API documentation](../../api/project_aliases.md) for
 more details.
-Once an alias has been created for a project (e.g., an alias `gitlab` for the
+After an alias has been created for a project (such as an alias `gitlab` for the
-project `https://gitlab.com/gitlab-org/gitlab`), the repository can be cloned
+project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository
-using the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of
+with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of
 `git clone git@gitlab.com:gitlab-org/gitlab.git`).
 ## Project activity analytics overview **(ULTIMATE SELF)**

--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -13,7 +13,7 @@ further restrictions on certain branches, they can be protected.
 ## Overview
-By default, a protected branch does four simple things:
+By default, a protected branch does these things:
 - It prevents its creation, if not already created, from everybody except users
  with Maintainer permission.
@@ -30,49 +30,47 @@ The default branch protection level is set in the [Admin Area](../admin_area/set
 ## Configuring protected branches
-To protect a branch, you need to have at least Maintainer permission level. Note
+To protect a branch, you need to have at least Maintainer permission level.
-that the `master` branch is protected by default.
+The `master` branch is protected by default.
-1. Navigate to your project's **Settings ➔ Repository**
+1. In your project, go to **Settings > Repository**.
 1. Scroll to find the **Protected branches** section.
 1. From the **Branch** dropdown menu, select the branch you want to protect and
   click **Protect**. In the screenshot below, we chose the `develop` branch.
   ![Protected branches page](img/protected_branches_page_v12_3.png)
-1. Once done, the protected branch will appear in the "Protected branches" list.
+1. Once done, the protected branch displays in the **Protected branches** list.
   ![Protected branches list](img/protected_branches_list_v12_3.png)
 ## Using the Allowed to merge and Allowed to push settings
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in GitLab 8.11.
 In GitLab 8.11 and later, we added another layer of branch protection which provides
-more granular management of protected branches. The "Developers can push"
+more granular management of protected branches. The **Developers can push**
-option was replaced by an "Allowed to push" setting which can be set to
+option was replaced by **Allowed to push**. You can set this value to allow
-allow/prohibit Maintainers and/or Developers to push to a protected branch.
+or prohibit Maintainers and/or Developers to push to a protected branch.
-Using the "Allowed to push" and "Allowed to merge" settings, you can control
+Using the **Allowed to push** and **Allowed to merge** settings, you can control
 the actions that different roles can perform with the protected branch.
-For example, you could set "Allowed to push" to "No one", and "Allowed to merge"
+For example, you could set **Allowed to push** to "No one", and **Allowed to merge**
-to "Developers + Maintainers", to require _everyone_ to submit a merge request for
+to "Developers + Maintainers", to require everyone to submit a merge request for
 changes going into the protected branch. This is compatible with workflows like
 the [GitLab workflow](../../topics/gitlab_flow.md).
 However, there are workflows where that is not needed, and only protecting from
 force pushes and branch removal is useful. For those workflows, you can allow
 everyone with write access to push to a protected branch by setting
-"Allowed to push" to "Developers + Maintainers".
+**Allowed to push** to "Developers + Maintainers".
-You can set the "Allowed to push" and "Allowed to merge" options while creating
+You can set the **Allowed to push** and **Allowed to merge** options while creating
 a protected branch or afterwards by selecting the option you want from the
-dropdown list in the "Already protected" area.
+dropdown list in the **Already protected** area.
 ![Developers can push](img/protected_branches_devs_can_push_v12_3.png)
 If you don't choose any of those options while creating a protected branch,
-they are set to "Maintainers" by default.
+they are set to Maintainers by default.
 ### Allow Deploy Keys to push to a protected branch
@@ -88,7 +86,7 @@ Deploy keys can be selected in the **Allowed to push** dropdown when:
 - Defining a protected branch.
 - Updating an existing branch.
-Select a deploy key to allow the owner of the key to push to the chosen protected branch,
+Select a deploy key to allow the key's owner to push to the chosen protected branch,
 even if they aren't a member of the related project. The owner of the selected deploy
 key must have at least read access to the given project.
@@ -103,24 +101,20 @@ Deploy Keys are not available in the **Allowed to merge** dropdown.
 ## Restricting push and merge access to certain users **(STARTER)**
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.11.
 With GitLab Enterprise Edition you can restrict access to protected branches
-by choosing a role (Maintainers, Developers) as well as certain users. From the
+by choosing a role (Maintainers, Developers) and certain users. From the
 dropdown menu select the role and/or the users you want to have merge or push
 access.
 ![Select roles and users](img/protected_branches_select_roles_and_users.png)
-Click **Protect** and the branch will appear in the "Protected branch" list.
+Click **Protect** and the branch displays in the **Protected branch** list.
 ![Roles and users list](img/protected_branches_select_roles_and_users_list.png)
 ## Wildcard protected branches
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665) in GitLab 8.10.
+You can specify a wildcard protected branch, which protects all branches
-You can specify a wildcard protected branch, which will protect all branches
 matching the wildcard. For example:
 | Wildcard Protected Branch | Matching Branches                                      |
@@ -129,15 +123,15 @@ matching the wildcard. For example:
 | `production/*`            | `production/app-server`, `production/load-balancer`    |
 | `*gitlab*`                | `gitlab`, `gitlab/staging`, `master/gitlab/production` |
-Protected branch settings (like "Developers can push") apply to all matching
+Protected branch settings, like **Developers can push**, apply to all matching
 branches.
 Two different wildcards can potentially match the same branch. For example,
 `*-stable` and `production-*` would both match a `production-stable` branch.
 In that case, if _any_ of these protected branches have a setting like
-"Allowed to push", then `production-stable` will also inherit this setting.
+"Allowed to push", then `production-stable` also inherit this setting.
-If you click on a protected branch's name, you will be presented with a list of
+If you click on a protected branch's name, GitLab displays a list of
 all matching branches:
 ![Protected branch matches](img/protected_branches_matches.png)
@@ -151,41 +145,36 @@ When a protected branch or wildcard protected branches are set to
 Developers (and users with higher [permission levels](../permissions.md)) are
 allowed to create a new protected branch as long as they are
 [**Allowed to merge**](#using-the-allowed-to-merge-and-allowed-to-push-settings).
-This can only be done via the UI or through the API (to avoid creating protected
+This can only be done by using the UI or through the API, to avoid creating protected
-branches accidentally from the command line or from a Git client application).
+branches accidentally from the command line or from a Git client application.
 To create a new branch through the user interface:
-1. Visit **Repository > Branches**.
+1. Go to **Repository > Branches**.
 1. Click on **New branch**.
-1. Fill in the branch name and select an existing branch, tag, or commit that
+1. Fill in the branch name and select an existing branch, tag, or commit to
-   the new branch will be based off. Only existing protected branches and commits
+   base the new branch on. Only existing protected branches and commits
-   that are already in protected branches will be accepted.
+   that are already in protected branches are accepted.
 ## Deleting a protected branch
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393) in GitLab 9.3.
+From time to time, you may need to delete or clean up protected branches.
+User with [Maintainer permissions](../permissions.md) and greater can manually delete protected
-From time to time, it may be required to delete or clean up branches that are
+branches by using the GitLab web interface:
-protected.
-User with [Maintainer permissions](../permissions.md) and up can manually delete protected
+1. Go to **Repository > Branches**.
-branches via the GitLab web interface:
+1. Click on the delete icon next to the branch you wish to delete.
+1. To prevent accidental deletion, an additional confirmation is required.
-1. Visit **Repository > Branches**
-1. Click on the delete icon next to the branch you wish to delete
-1. In order to prevent accidental deletion, an additional confirmation is
-   required
   ![Delete protected branches](img/protected_branches_delete.png)
-Deleting a protected branch is only allowed via the web interface, not via Git.
+Deleting a protected branch is allowed only by using the web interface; not from Git.
 This means that you can't accidentally delete a protected branch from your
 command line or a Git client application.
 ## Protected Branches approval by Code Owners **(PREMIUM)**
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4.
 It is possible to require at least one approval by a
 [Code Owner](code_owners.md) to a file changed by the
@@ -208,7 +197,7 @@ To enable Code Owner's approval to branches already protected:
 ![Code Owners approval - branch already protected](img/code_owners_approval_protected_branch_v12_4.png)
-When enabled, all merge requests targeting these branches will require approval
+When enabled, all merge requests targeting these branches require approval
 by a Code Owner per matched rule before they can be merged.
 Additionally, direct pushes to the protected branch are denied if a rule is matched.
@@ -224,26 +213,9 @@ for details about the pipelines security model.
 ## Changelog
-**13.5**
+- **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769).
+- **11.9**: [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361)
- [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769).
+  by Developers (and users with higher permission levels) through the API and the user interface.
-**11.9**
- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface.
-**9.2**
- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393)).
-**8.11**
- Allow creating protected branches that can't be pushed to ([merge request !5081](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081)).
-**8.10**
- Allow developers without push access to merge into a protected branch ([merge request !4892](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4892)).
- Allow specifying protected branches using wildcards ([merge request !4665](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665)).
 <!-- ## Troubleshooting

--- a/doc/user/project/protected_tags.md
+++ b/doc/user/project/protected_tags.md
@@ -15,11 +15,13 @@ This feature evolved out of [protected branches](protected_branches.md)
 ## Overview
-Protected tags will prevent anyone from updating or deleting the tag, and will prevent creation of matching tags based on the permissions you have selected. By default, anyone without Maintainer permission will be prevented from creating tags.
+Protected tags prevent anyone from updating or deleting the tag, and prevent
+creation of matching tags based on the permissions you have selected. By default,
+anyone without Maintainer [permissions](../permissions.md) is prevented from creating tags.
 ## Configuring protected tags
-To protect a tag, you need to have at least Maintainer permission level.
+To protect a tag, you need to have at least Maintainer [permissions](../permissions.md).
 1. Navigate to the project's **Settings > Repository**:
@@ -29,17 +31,18 @@ To protect a tag, you need to have at least Maintainer permission level.
   ![Protected tags page](img/protected_tags_page_v12_3.png)
-1. From the **Allowed to create** dropdown, select who will have permission to create matching tags and then click **Protect**:
+1. From the **Allowed to create** dropdown, select users with permission to create
+   matching tags, and click **Protect**:
   ![Allowed to create tags dropdown](img/protected_tags_permissions_dropdown_v12_3.png)
-1. Once done, the protected tag will appear in the **Protected tags** list:
+1. After done, the protected tag displays in the **Protected tags** list:
   ![Protected tags list](img/protected_tags_list_v12_3.png)
 ## Wildcard protected tags
-You can specify a wildcard protected tag, which will protect all tags
+You can specify a wildcard protected tag, which protects all tags
 matching the wildcard. For example:
 | Wildcard Protected Tag | Matching Tags                 |
@@ -52,9 +55,9 @@ matching the wildcard. For example:
 Two different wildcards can potentially match the same tag. For example,
 `*-stable` and `production-*` would both match a `production-stable` tag.
 In that case, if _any_ of these protected tags have a setting like
-**Allowed to create**, then `production-stable` will also inherit this setting.
+**Allowed to create**, then `production-stable` also inherit this setting.
-If you click on a protected tag's name, you will be presented with a list of
+If you click on a protected tag's name, GitLab displays a list of
 all matching tags:
 ![Protected tag matches](img/protected_tag_matches.png)