Refactor "Allow edits from maintainers in forks" docs

5 files changed, 68 insertions, 7 deletions

diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md
index 859ac92ef89..da6e6b5fd3a 100644
--- a/doc/user/project/merge_requests/allow_collaboration.md
+++ b/doc/user/project/merge_requests/allow_collaboration.md
@@ -1,20 +1,72 @@
 # Allow collaboration on merge requests across forks
 
-> [Introduced][ce-17395] in GitLab 10.6.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17395)
+  in GitLab 10.6.
+
+When a user opens a merge request from a fork, they are given the option to allow
+upstream members to collaborate with them on the source branch. This allows
+the members of the upstream project to make small fixes or rebase branches
+before merging, reducing the back and forth of accepting external contributions.
 
 This feature is available for merge requests across forked projects that are
-publicly accessible. It makes it easier for members of projects to
-collaborate on merge requests across forks.
+publicly accessible.
 
 When enabled for a merge request, members with merge access to the target
 branch of the project will be granted write permissions to the source branch
 of the merge request.
 
+## Enabling commit edits from upstream members
+
 The feature can only be enabled by users who already have push access to the
-source project, and only lasts while the merge request is open.
+source project and only lasts while the merge request is open. Once enabled,
+upstream members will also be able to retry the pipelines and jobs of the
+merge request:
+
+1. Enable the contribution while creating or editing a merge request.
+
+   ![Enable contribution](img/allow_collaboration.png)
+
+1. Once the merge request is created, you'll see that commits from members who
+   can merge to the target branch are allowed.
+
+   ![Check that contribution is enabled](img/allow_collaboration_after_save.png)
+
+## Pushing to the fork as the upstream member
+
+If the creator of the merge request has enabled contributions from upstream
+members, you can push directly to the branch of the forked repository.
+
+Assuming that:
+
+- The forked project URL is `git@gitlab.com:thedude/awesome-project.git`.
+- The branch of the merge request is `update-docs`.
+
+Here's how the process would look like:
+
+1. First, you need to get the changes that the merge request has introduced.
+   Click the **Check out branch** button that has some pre-populated
+   commands that you can run.
+
+   ![Check out branch button](img/checkout_button.png)
+
+1. Use the copy to clipboard button to copy the first command and paste them
+   in your terminal:
+
+   ```sh
+   git fetch git@gitlab.com:thedude/awesome-project.git update-docs
+   git checkout -b thedude-awesome-project-update-docs FETCH_HEAD
+   ```
+
+   This will fetch the branch of the forked project and then create a local branch
+   based off the fetched branch.
 
-Enable this functionality while creating or editing a merge request:
+1. Make any changes you want and commit.
+1. Push to the forked project:
 
-![Enable collaboration](./img/allow_collaboration.png)
+   ```sh
+   git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs
+   ```
 
-[ce-17395]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17395
+   Note the colon (`:`) between the two branches. The above command will push the
+   local branch `thedude-awesome-project-update-docs` to the
+   `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository.
diff --git a/doc/user/project/merge_requests/img/allow_collaboration.png b/doc/user/project/merge_requests/img/allow_collaboration.png
index 3c81e4c27b8..e40e8a6b11c 100644
--- a/doc/user/project/merge_requests/img/allow_collaboration.png
+++ b/doc/user/project/merge_requests/img/allow_collaboration.png
diff --git a/doc/user/project/merge_requests/img/allow_collaboration_after_save.png b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png
new file mode 100644
index 00000000000..4ba4c84c8c5
--- /dev/null
+++ b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png
diff --git a/doc/user/project/merge_requests/img/checkout_button.png b/doc/user/project/merge_requests/img/checkout_button.png
new file mode 100644
index 00000000000..9850795c9b4
--- /dev/null
+++ b/doc/user/project/merge_requests/img/checkout_button.png
diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index f479f9e4ef6..9015a964781 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -92,6 +92,15 @@ request widget will show the "Removes source branch" text.
 
 ![Remove source branch status](img/remove_source_branch_status.png)
 
+## Allow collaboration on merge requests across forks
+
+When a user opens a merge request from a fork, they are given the option to allow
+upstream maintainers to collaborate with them on the source branch. This allows
+the maintainers of the upstream project to make small fixes or rebase branches
+before merging, reducing the back and forth of accepting community contributions.
+
+[Learn more about allowing upstream members to push to forks.](allow_collaboration.md)
+
 ## Authorization for merge requests
 
 There are two main ways to have a merge request flow with GitLab: