From c5661fecf6f84851ff727a5ab006a6b414dfa28a Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 16 Jan 2019 12:52:24 +0100 Subject: Refactor "Allow edits from maintainers in forks" docs --- .../project/merge_requests/allow_collaboration.md | 66 ++++++++++++++++++--- .../merge_requests/img/allow_collaboration.png | Bin 21522 -> 11028 bytes .../img/allow_collaboration_after_save.png | Bin 0 -> 5415 bytes .../project/merge_requests/img/checkout_button.png | Bin 0 -> 5977 bytes doc/user/project/merge_requests/index.md | 9 +++ 5 files changed, 68 insertions(+), 7 deletions(-) create mode 100644 doc/user/project/merge_requests/img/allow_collaboration_after_save.png create mode 100644 doc/user/project/merge_requests/img/checkout_button.png 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 Binary files a/doc/user/project/merge_requests/img/allow_collaboration.png and b/doc/user/project/merge_requests/img/allow_collaboration.png differ 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 Binary files /dev/null and b/doc/user/project/merge_requests/img/allow_collaboration_after_save.png differ 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 Binary files /dev/null and b/doc/user/project/merge_requests/img/checkout_button.png differ 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: -- cgit v1.2.1