Merge branch 'aqualls-20211027-suggestions-flag' into 'master'

Start bringing suggestions flag up to spec

See merge request gitlab-org/gitlab!73210

doc/user/project/merge_requests/reviews/suggestions.md

@@ -7,14 +7,13 @@ type: index, reference
 
 # Suggest changes **(FREE)**
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6.
-> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../../../feature_flags.md), disabled by default.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) custom commit messages for suggestions in GitLab 13.9 [with a flag](../../../../administration/feature_flags.md) named `suggestions_custom_commit`. Disabled by default.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10.
 
 As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request
 diff threads. Then, the merge request author (or other users with appropriate
-[permission](../../../permissions.md)) is able to apply these suggestions with a click,
-which generates a commit in the merge request authored by the user that suggested the changes.
+[permission](../../../permissions.md)) can apply these suggestions with a click.
+This action generates a commit in the merge request, authored by the user that suggested the changes.
 
 1. Choose a line of code to be changed, add a new comment, then select
    the **Insert suggestion** icon in the toolbar:
@@ -38,14 +37,15 @@ which generates a commit in the merge request authored by the user that suggeste
 
    ![Custom commit](img/custom_commit_v13_9.png)
 
-After the author applies a suggestion, it's marked with the **Applied** label,
-the thread is automatically resolved, and GitLab creates a new commit
-and pushes the suggested change directly into the codebase in the merge request's
-branch. The [Developer role](../../../permissions.md) is required to do so.
+After the author applies a suggestion:
 
-## Multi-line suggestions
+1. The suggestion is marked as **Applied**.
+1. The thread is resolved.
+1. GitLab creates a new commit with the changes.
+1. If the user has the [Developer role](../../../permissions.md), GitLab pushes
+   the suggested change directly into the codebase in the merge request's branch.
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10.
+## Multi-line suggestions
 
 Reviewers can also suggest changes to multiple lines with a single suggestion
 within merge request diff threads by adjusting the range offsets. The
@@ -67,9 +67,9 @@ suggestion.
 
 ## Code block nested in suggestions
 
-If you need to make a suggestion that involves a
-[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks
-instead of the usual three.
+To add a suggestion that includes a
+[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion
+in four backticks instead of three:
 
 ![A comment editor with a suggestion with a fenced code block](img/suggestion_code_block_editor_v12_8.png)
 
@@ -95,14 +95,14 @@ You can also use following variables besides static text:
 
 | Variable               | Description | Output example |
 |------------------------|-------------|----------------|
-| `%{branch_name}`       | The name of the branch the suggestion(s) was(were) applied to. | `my-feature-branch` |
-| `%{files_count}`       | The number of file(s) to which suggestion(s) was(were) applied.| **2** |
-| `%{file_paths}`        | The path(s) of the file(s) suggestion(s) was(were) applied to. Paths are separated by commas.| `docs/index.md, docs/about.md` |
+| `%{branch_name}`       | The name of the branch to which suggestions were applied. | `my-feature-branch` |
+| `%{files_count}`       | The number of files to which suggestions were applied.| **2** |
+| `%{file_paths}`        | The paths of the file to which suggestions were applied. Paths are separated by commas.| `docs/index.md, docs/about.md` |
 | `%{project_path}`      | The project path. | `my-group/my-project` |
 | `%{project_name}`      | The human-readable name of the project. | **My Project** |
 | `%{suggestions_count}` | The number of suggestions applied.| **3** |
-| `%{username}`          | The username of the user applying suggestion(s). | `user_1` |
-| `%{user_full_name}`    | The full name of the user applying suggestion(s). | **User 1** |
+| `%{username}`          | The username of the user applying suggestions. | `user_1` |
+| `%{user_full_name}`    | The full name of the user applying suggestions. | **User 1** |
 
 For example, to customize the commit message to output
 **Addresses user_1's review**, set the custom text to
@@ -114,32 +114,32 @@ introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381).
 
 ## Batch suggestions
 
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) with a flag named `batch_suggestions`, disabled by default.
 > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2.
-> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11.
-> - Custom commit messages for batch suggestions [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) in GitLab 14.4.
+> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4.
 
 You can apply multiple suggestions at once to reduce the number of commits added
 to your branch to address your reviewers' requests.
 
 1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**:
 
-   ![A code change suggestion displayed, with the button to add the suggestion to a batch highlighted.](img/add_first_suggestion_to_batch_v13_1.jpg "Add a suggestion to a batch")
+   ![A code change suggestion displayed, with the add-suggestion option highlighted.](img/add_first_suggestion_to_batch_v13_1.jpg "Add a suggestion to a batch")
 
 1. Add as many additional suggestions to the batch as you wish:
 
-   ![A code change suggestion displayed, with the button to add an additional suggestion to a batch highlighted.](img/add_another_suggestion_to_batch_v13_1.jpg "Add another suggestion to a batch")
+   ![A code change suggestion displayed, with the add-more suggestion option highlighted.](img/add_another_suggestion_to_batch_v13_1.jpg "Add another suggestion to a batch")
 
 1. To remove suggestions, select **Remove from batch**:
 
-   ![A code change suggestion displayed, with the button to remove that suggestion from its batch highlighted.](img/remove_suggestion_from_batch_v13_1.jpg "Remove a suggestion from a batch")
+   ![A code change suggestion displayed, with the option to remove that suggestion from its batch highlighted.](img/remove_suggestion_from_batch_v13_1.jpg "Remove a suggestion from a batch")
 
 1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**. You
    can optionally specify a custom commit message for [batch suggestions](#batch-suggestions)
    (GitLab 14.4 and later) to describe your change. If you don't specify it, the default commit
    message is used.
 
-   ![A code change suggestion displayed, with the button to apply the batch of suggestions highlighted.](img/apply_batch_of_suggestions_v13_1.jpg "Apply a batch of suggestions")
+   ![A code change suggestion displayed, with the option to apply the batch of suggestions highlighted.](img/apply_batch_of_suggestions_v13_1.jpg "Apply a batch of suggestions")
 
 WARNING:
 Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions.