Refactor protected branches documentation

13 files changed, 115 insertions, 62 deletions

diff --git a/app/views/projects/protected_branches/index.html.haml b/app/views/projects/protected_branches/index.html.haml
index 151e1d64851..950df740bbc 100644
--- a/app/views/projects/protected_branches/index.html.haml
+++ b/app/views/projects/protected_branches/index.html.haml
@@ -6,12 +6,13 @@
       = page_title
     %p Keep stable branches secure and force developers to use merge requests.
     %p.prepend-top-20
-      Protected branches are designed to:
+      By default, protected branches are designed to:
       %ul
-        %li prevent pushes from everybody except #{link_to "masters", help_page_path("user/permissions"), class: "vlink"}
-        %li prevent anyone from force pushing to the branch
-        %li prevent anyone from deleting the branch
-      %p.append-bottom-0 Read more about #{link_to "project permissions", help_page_path("user/permissions"), class: "underlined-link"}
+        %li prevent their creation, if not already created, from everybody except Masters
+        %li prevent pushes from everybody except Masters
+        %li prevent <strong>anyone</strong> from force pushing to the branch
+        %li prevent <strong>anyone</strong> from deleting the branch
+      %p.append-bottom-0 Read more about #{link_to "protected branches", help_page_path("user/project/protected_branches"), class: "underlined-link"} and #{link_to "project permissions", help_page_path("user/permissions"), class: "underlined-link"}.
   .col-lg-9
     %h5.prepend-top-0
       Protect a branch
@@ -23,7 +24,7 @@
           = f.label :name, "Branch", class: "label-light"
           = render partial: "dropdown", locals: { f: f }
           %p.help-block
-            = link_to "Wildcards", help_page_path('workflow/protected_branches', anchor: "wildcard-protected-branches")
+            = link_to "Wildcards", help_page_path('user/project/protected_branches', anchor: "wildcard-protected-branches")
             such as
             %code *-stable
             or
diff --git a/doc/user/project/img/project_settings_list.png b/doc/user/project/img/project_settings_list.png
new file mode 100644
index 00000000000..57ca2ac5f9e
--- /dev/null
+++ b/doc/user/project/img/project_settings_list.png
diff --git a/doc/user/project/img/protected_branches_choose_branch.png b/doc/user/project/img/protected_branches_choose_branch.png
new file mode 100644
index 00000000000..26328143717
--- /dev/null
+++ b/doc/user/project/img/protected_branches_choose_branch.png
diff --git a/doc/user/project/img/protected_branches_devs_can_push.png b/doc/user/project/img/protected_branches_devs_can_push.png
new file mode 100644
index 00000000000..9c33db36586
--- /dev/null
+++ b/doc/user/project/img/protected_branches_devs_can_push.png
diff --git a/doc/user/project/img/protected_branches_error_ui.png b/doc/user/project/img/protected_branches_error_ui.png
new file mode 100644
index 00000000000..cc61df7ca97
--- /dev/null
+++ b/doc/user/project/img/protected_branches_error_ui.png
diff --git a/doc/user/project/img/protected_branches_list.png b/doc/user/project/img/protected_branches_list.png
new file mode 100644
index 00000000000..9f070f7a208
--- /dev/null
+++ b/doc/user/project/img/protected_branches_list.png
diff --git a/doc/user/project/img/protected_branches_matches.png b/doc/user/project/img/protected_branches_matches.png
new file mode 100644
index 00000000000..30ce53f704e
--- /dev/null
+++ b/doc/user/project/img/protected_branches_matches.png
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
new file mode 100644
index 00000000000..6a8170b5ecb
--- /dev/null
+++ b/doc/user/project/protected_branches.md
@@ -0,0 +1,106 @@
+# Protected Branches
+
+[Permissions](../permissions.md) in GitLab are fundamentally defined around the
+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.
+
+By default, a protected branch does four simple things:
+
+- it prevents its creation, if not already created, from everybody except users
+  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
+
+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. 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**.
+
+    ![Project settings list](img/project_settings_list.png)
+
+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.
+
+    ![Choose protected branch](img/protected_branches_choose_branch.png)
+
+1. Once done, the protected branch will appear in the "Already protected" list.
+
+    ![Protected branches list](img/protected_branches_list.png)
+
+
+Since GitLab 8.10, we added another layer of branch protection which provides
+more granular management of protected branches. You can now choose the option
+"Developers can merge" so that Developer users can merge a merge request but
+not directly push. In that case, your branches are protected from direct pushes,
+yet Developers don't need elevated permissions or wait for someone with a higher
+permission level to press merge.
+
+You can set this option while creating the protected branch or after its
+creation.
+
+## Wildcard protected branches
+
+>**Note:**
+This feature was [introduced][ce-4665] in GitLab 8.10.
+
+You can specify a wildcard protected branch, which will protect all branches
+matching the wildcard. For example:
+
+| Wildcard Protected Branch | Matching Branches                                      |
+|---------------------------+--------------------------------------------------------|
+| `*-stable`                | `production-stable`, `staging-stable`                  |
+| `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
+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.
+
+If you click on a protected branch's name that is created using a wildcard,
+you will be presented with a list of all matching branches:
+
+![Protected branch matches](img/protected_branches_matches.png)
+
+## Restrict the creation of protected branches
+
+Creating a protected branch or a list of protected branches using the wildcard
+feature, not only you are restricting pushes to those branches, but also their
+creation if not already created.
+
+## Error messages when pushing to a protected branch
+
+A user with insufficient permissions will be presented with an error when
+creating or pushing to a branch that's prohibited, either through GitLab's UI:
+
+![Protected branch error GitLab UI](img/protected_branches_error_ui.png)
+
+or using Git from their terminal:
+
+```bash
+remote: GitLab: You are not allowed to push code to protected branches on this project.
+To https://gitlab.example.com/thedude/bowling.git
+ ! [remote rejected] staging-stable -> staging-stable (pre-receive hook declined)
+error: failed to push some refs to 'https://gitlab.example.com/thedude/bowling.git'
+```
+
+## Changelog
+
+**8.10.0**
+
+- Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!5081][ce-4665]
+
+---
+
+[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"
diff --git a/doc/workflow/README.md b/doc/workflow/README.md
index ddb2f7281b1..49dec613716 100644
--- a/doc/workflow/README.md
+++ b/doc/workflow/README.md
@@ -12,7 +12,7 @@
 - [Project Features](project_features.md)
 - [Project forking workflow](forking_workflow.md)
 - [Project users](add-user/add-user.md)
-- [Protected branches](protected_branches.md)
+- [Protected branches](../user/project/protected_branches.md)
 - [Sharing a project with a group](share_with_group.md)
 - [Share projects with other groups](share_projects_with_other_groups.md)
 - [Web Editor](web_editor.md)
diff --git a/doc/workflow/protected_branches.md b/doc/workflow/protected_branches.md
index 5c1c7b47c8a..aa48b8f750e 100644
--- a/doc/workflow/protected_branches.md
+++ b/doc/workflow/protected_branches.md
@@ -1,55 +1 @@
-# Protected Branches
-
-Permissions in GitLab are fundamentally defined around the 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 three simple things:
-
-* 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
-
-You can make any branch a protected branch. GitLab makes the master branch a protected branch by default.
-
-To protect a branch, user needs to have at least a Master permission level, see [permissions document](../user/permissions.md).
-
-![protected branches page](protected_branches/protected_branches1.png)
-
-Navigate to project settings page and select `protected branches`. From the `Branch` dropdown menu select the branch you want to protect.
-
-Some workflows, like [GitLab workflow](gitlab_flow.md), require all users with write access to submit a Merge request in order to get the code into a protected branch.
-
-Since Masters and Owners can already push to protected branches, that means Developers cannot push to protected branch and need to submit a Merge request.
-
-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 `Developers can push` check box.
-
-On already protected branches you can also allow developers to push to the repository by selecting the `Developers can push` check box.
-
-![Developers can push](protected_branches/protected_branches2.png)
-
-## Wildcard Protected Branches
-
->**Note:**
-This feature was added in GitLab 8.10.
-
-1. You can specify a wildcard protected branch, which will protect all branches matching the wildcard. For example:
-
-    | Wildcard Protected Branch | Matching Branches                                      |
-    |---------------------------+--------------------------------------------------------|
-    | `*-stable`                | `production-stable`, `staging-stable`                  |
-    | `production/*`            | `production/app-server`, `production/load-balancer`    |
-    | `*gitlab*`                | `gitlab`, `gitlab/staging`, `master/gitlab/production` |
-
-1. Protected branch settings (like "Developers Can Push") apply to all matching branches.
-
-1. Two different wildcards can potentially match the same branch. For example, `*-stable` and `production-*` would both match a `production-stable` branch.
-   >**Note:**
-   If _any_ of these protected branches have "Developers Can Push" set to true, then `production-stable` has it set to true.
-
-1. If you click on a protected branch's name, you will be presented with a list of all matching branches:
-
-    ![protected branch matches](protected_branches/protected_branches3.png)
-
+This document is moved to [user/project/protected_branches.md](../user/project/protected_branches.md)
diff --git a/doc/workflow/protected_branches/protected_branches1.png b/doc/workflow/protected_branches/protected_branches1.png
deleted file mode 100644
index c00443803de..00000000000
--- a/doc/workflow/protected_branches/protected_branches1.png
+++ /dev/null
diff --git a/doc/workflow/protected_branches/protected_branches2.png b/doc/workflow/protected_branches/protected_branches2.png
deleted file mode 100644
index a4f664d3b21..00000000000
--- a/doc/workflow/protected_branches/protected_branches2.png
+++ /dev/null
diff --git a/doc/workflow/protected_branches/protected_branches3.png b/doc/workflow/protected_branches/protected_branches3.png
deleted file mode 100644
index 2a50cb174bb..00000000000
--- a/doc/workflow/protected_branches/protected_branches3.png
+++ /dev/null