Commit 4044ef15 authored by Suzanne Selhorn's avatar Suzanne Selhorn

Merge branch 'axil-allow-collab-mr' into 'master'

Refactor the collaboration across forks docs

See merge request gitlab-org/gitlab!77457
parents aa50ad17 15775b40
......@@ -4,72 +4,97 @@ group: Code Review
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Allow collaboration on merge requests across forks **(FREE)**
# Collaborate on merge requests across forks **(FREE)**
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.
When you open a merge request from your fork, you can allow upstream
members to collaborate with you on your branch.
When you enable this option, members who have permission to merge to the target branch get
permission to write to the merge request's source branch.
The members of the upstream project can then make small fixes or rebase branches
before merging.
This feature is available for merge requests across forked projects that are
publicly accessible.
When enabled for a merge request, members with merge access to the target
branch of the project is granted write permissions to the source branch
of the merge request.
## Allow commits from upstream members
## Enabling commit edits from upstream members
> Enabled by default in [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308).
In [GitLab 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/23308),
this setting is enabled by default. It can be changed by users with the
Developer [role](../../permissions.md) for the source project. After it's enabled,
upstream members can retry the pipelines and jobs of the merge request:
As the author of a merge request, you can allow commit edits from
upstream members of the project you're contributing to:
1. While creating or editing a merge request, scroll to **Contribution** and
then select the **Allow commits from members who can merge to the target branch**.
select the **Allow commits from members who can merge to the target branch**
checkbox.
1. Finish creating your merge request.
After you create the merge request, the merge request widget displays a message:
**Members who can merge are allowed to add commits.**
After you create the merge request, the merge request widget displays the message
**Members who can merge are allowed to add commits**. Upstream members can then
commit directly to your branch, as well as retry the pipelines and jobs of the
merge request.
## Prevent commits from upstream members
## Pushing to the fork as the upstream member
As the author of a merge request, you can prevent commit edits from
upstream members of the project you're contributing to:
If the creator of the merge request has enabled contributions from upstream
members, you can push directly to the branch of the forked repository.
1. While creating or editing a merge request, scroll to **Contribution** and
clear the **Allow commits from members who can merge to the target branch**
checkbox.
1. Finish creating your merge request.
Assuming that:
## Push to the fork as the upstream member
- The forked project URL is `git@gitlab.com:thedude/awesome-project.git`.
- The branch of the merge request is `update-docs`.
You can push directly to the branch of the forked repository if:
To find and work with the changes from the fork:
- The author of the merge request has enabled contributions from upstream
members.
- You have at least the [Developer role](../../permissions.md) in the
upstream project.
In the following example:
- The forked repository URL is `git@gitlab.com:contributor/forked-project.git`.
- The branch of the merge request is `fork-branch`.
To change or add a commit to the contributor's merge request:
1. Open the merge request page, and select the **Overview** tab.
1. Scroll to the merge request widget, and select **Check out branch**:
![Check out branch button](img/commit-button_v13_12.png)
1. In the modal window, select **{copy-to-clipboard}** (**Copy**) for step 1
to copy the `git fetch` and `git checkout` instructions to your clipboard.
Paste the commands (which look like this example) into your terminal:
1. Scroll to the merge request widget, and select **Check out branch**.
1. In the modal window, select **Copy** (**{copy-to-clipboard}**).
1. In your terminal, navigate to your cloned version of the repository, and
paste the commands. For example:
```shell
git fetch git@gitlab.com:thedude/awesome-project.git update-docs
git checkout -b thedude-awesome-project-update-docs FETCH_HEAD
git fetch "git@gitlab.com:contributor/forked-project.git" 'fork-branch'
git checkout -b contributor/fork-branch' FETCH_HEAD
```
These commands fetch the branch from the forked project, and create a local branch
based off the fetched branch.
Those commands fetch the branch from the forked project, and create a local branch
for you to work on.
1. Make your changes to the local copy of the branch, and then commit them.
1. In your terminal, push your local changes back up to the forked project. This
command pushes the local branch `thedude-awesome-project-update-docs` to the
`update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository:
1. Make your changes to your local copy of the branch, and then commit them.
1. Push your local changes to the forked project. The following command pushes
the local branch `contributor/fork-branch` to the `fork-branch` branch of
the `git@gitlab.com:contributor/forked-project.git` repository:
```shell
git push git@gitlab.com:thedude/awesome-project.git thedude-awesome-project-update-docs:update-docs
git push git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch
```
Note the colon (`:`) between the two branches.
If you have amended or squashed any commits, you must force push. Proceed
with caution as this command rewrites the commit history:
```shell
git push --force git@gitlab.com:contributor/forked-project.git contributor/fork-branch:fork-branch
```
Note the colon (`:`) between the two branches. The general scheme is:
```shell
git push <forked_repository_git_url> <local_branch>:<fork_branch>
```
## Troubleshooting
......@@ -86,14 +111,3 @@ going back to the original project:
1. Create a group containing all the upstream members.
1. Go to the **Project information > Members** page in the forked project and invite the newly-created
group to the forked project.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment