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

Refactor the collaboration across forks docs

See merge request gitlab-org/gitlab!77457

doc/user/project/merge_requests/allow_collaboration.md

@@ -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. -->