Edit docs for new changes of protected branchesprotected-branches-doc-refactor

4 files changed, 35 insertions, 27 deletions

diff --git a/doc/user/project/img/protected_branches_devs_can_push.png b/doc/user/project/img/protected_branches_devs_can_push.png
index 308743c3e80..9c33db36586 100644
--- a/doc/user/project/img/protected_branches_devs_can_push.png
+++ b/doc/user/project/img/protected_branches_devs_can_push.png
diff --git a/doc/user/project/img/protected_branches_list.png b/doc/user/project/img/protected_branches_list.png
index 9a5b973c423..0c093f8fe3f 100644
--- a/doc/user/project/img/protected_branches_list.png
+++ b/doc/user/project/img/protected_branches_list.png
diff --git a/doc/user/project/img/protected_branches_page.png b/doc/user/project/img/protected_branches_page.png
index ec0683febee..860619300ea 100644
--- a/doc/user/project/img/protected_branches_page.png
+++ b/doc/user/project/img/protected_branches_page.png
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
index 6c5abf936a0..fdd926dca46 100644
--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -5,12 +5,11 @@ idea of having read or write permission to the repository and branches. To
 prevent people from messing with history or pushing code without review, we've
 created protected branches.
 
-A protected branch does four simple things:
+By default, a protected branch does four simple things:
 
 - it prevents its creation, if not already created, from everybody except users
-  with Master and/or Developer permission if configured
-- it prevents pushes from everybody except users with Master and/or Developer
-  permission if configured
+  with Master permission
+- it prevents pushes from everybody except users with Master permission
 - it prevents **anyone** from force pushing to the branch
 - it prevents **anyone** from deleting the branch
 
@@ -18,8 +17,8 @@ See the [Changelog](#changelog) section for changes over time.
 
 ## Configuring protected branches
 
-To protect a branch, you need to have at least Master permission level. The
-master branch is protected by default.
+To protect a branch, you need to have at least Master permission level. Note
+that the `master` branch is protected by default.
 
 1. Navigate to the main page of the project.
 1. In the upper right corner, click the settings wheel and select **Protected branches**.
@@ -27,7 +26,7 @@ master branch is protected by default.
     ![Project settings list](img/project_settings_list.png)
 
 1. From the **Branch** dropdown menu, select the branch you want to protect and
-   click **Protect**.
+   click **Protect**. In the screenshot below, we chose the `develop` branch.
 
     ![Protected branches page](img/protected_branches_page.png)
 
@@ -35,24 +34,37 @@ master branch is protected by default.
 
     ![Protected branches list](img/protected_branches_list.png)
 
----
+## Using the Allowed to push and Allowed to merge settings
+
+>**Note:**
+This feature was [introduced][ce-5081] in GitLab 8.10.
+
+Since GitLab 8.10, we added another layer of branch protection which provides
+more granular management of protected branches. The "Developers can push"
+option was replaced by an "Allowed to push" setting which can be set to
+allow/prohibit Masters and/or Developers to push to a protected branch.
 
-Some workflows, like the [GitLab workflow](../../workflow/gitlab_flow.md),
-require all users with write access to submit a Merge request in order to get
-the changes into a protected branch. Since Masters and Owners can already push
-to protected branches, that means Developers cannot push to them and need to
-submit a Merge request.
+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"
+to "Developers + Masters", to require _everyone_ to submit an MR for changes
+going into the protected branch. This is compatible with workflows like the
+[GitLab workflow](../../workflow/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 selecting the
-"Developers can push" check box.
+everyone with write access to push to a protected branch by setting
+"Allowed to push" to "Developers + Masters".
 
-You can set this option while creating a protected branch or afterwards by
-selecting the "Developers can push" check box.
+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.
 
 ![Developers can push](img/protected_branches_devs_can_push.png)
 
+If you don't choose any of those options while creating a protected branch,
+they are set to "Masters" by default.
+
 ## Wildcard protected branches
 
 >**Note:**
@@ -72,8 +84,8 @@ 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 "Developers can push"
-set to true, then `production-stable` will also have set to true.
+In that case, if _any_ of these protected branches have a setting like
+"Allowed to push", then `production-stable` will also inherit this setting.
 
 If you click on a protected branch's name, you will be presented with a list of
 all matching branches:
@@ -86,14 +98,10 @@ all matching branches:
 
 **8.10**
 
-Since GitLab 8.10, we added another layer of branch protection which provides
-more granular management of protected branches. The "Developers can push"
-option was replaced by an "Allowed to push" setting which can be set to
-allow/prohibit Masters and/or Developers to push to a protected branch.
-
-See [gitlab-org/gitlab-ce!5081][5081] for implementation details.
+- Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!5081][ce-5081]
+- Allow creating protected branches that can't be pushed to [gitlab-org/gitlab-ce!5081][ce-4665]
 
 ---
 
-[ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665
-[ce-5081]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5081
+[ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665 "Allow specifying protected branches using wildcards"
+[ce-5081]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5081 "Allow creating protected branches that can't be pushed to"