Merge branch '327754-aqualls-make-subdir' into 'master'

Start cleanup of "threads" page

See merge request gitlab-org/gitlab!60870

app/serializers/merge_request_widget_entity.rb

@@ -52,7 +52,7 @@ class MergeRequestWidgetEntity < Grape::Entity
   end
 
   expose :reviewing_and_managing_merge_requests_docs_path do |merge_request|
-    help_page_path('user/project/merge_requests/reviewing_and_managing_merge_requests.md', anchor: "checkout-merge-requests-locally-through-the-head-ref")
+    help_page_path('user/project/merge_requests/reviews/index.md', anchor: "checkout-merge-requests-locally-through-the-head-ref")
   end
 
   expose :merge_request_pipelines_docs_path do |merge_request|

app/views/projects/_merge_request_merge_suggestions_settings.html.haml

@@ -3,7 +3,7 @@
 .form-group
   %b= s_('ProjectSettings|Merge suggestions')
   %p.text-secondary
-    - configure_the_commit_message_for_applied_suggestions_help_link_url = help_page_path('user/discussions/index.md', anchor: 'configure-the-commit-message-for-applied-suggestions')
+    - configure_the_commit_message_for_applied_suggestions_help_link_url = help_page_path('user/project/merge_requests/reviews/suggestions.md', anchor: 'configure-the-commit-message-for-applied-suggestions')
     - configure_the_commit_message_for_applied_suggestions_help_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: configure_the_commit_message_for_applied_suggestions_help_link_url }
     = s_('ProjectSettings|The commit message used when applying merge request suggestions. %{link_start}Learn more about suggestions.%{link_end}').html_safe % { link_start: configure_the_commit_message_for_applied_suggestions_help_link_start, link_end: '</a>'.html_safe }
   .mb-2

app/views/projects/merge_requests/_widget.html.haml

@@ -5,7 +5,7 @@
 
     window.gl.mrWidgetData.squash_before_merge_help_path = '#{help_page_path("user/project/merge_requests/squash_and_merge")}';
     window.gl.mrWidgetData.ci_troubleshooting_docs_path = '#{help_page_path('ci/troubleshooting.md')}';
-    window.gl.mrWidgetData.mr_troubleshooting_docs_path = '#{help_page_path('user/project/merge_requests/reviewing_and_managing_merge_requests.md', anchor: 'troubleshooting')}';
+    window.gl.mrWidgetData.mr_troubleshooting_docs_path = '#{help_page_path('user/project/merge_requests/reviews/index.md', anchor: 'troubleshooting')}';
     window.gl.mrWidgetData.pipeline_must_succeed_docs_path = '#{help_page_path('user/project/merge_requests/merge_when_pipeline_succeeds.md', anchor: 'only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds')}';
     window.gl.mrWidgetData.security_approvals_help_page_path = '#{help_page_path('user/application_security/index.md', anchor: 'security-approvals-in-merge-requests')}';
     window.gl.mrWidgetData.license_compliance_docs_path = '#{help_page_path('user/compliance/license_compliance/index.md', anchor: 'policies')}';

app/views/projects/merge_requests/show.html.haml

@@ -5,7 +5,7 @@
 - page_title "#{@merge_request.title} (#{@merge_request.to_reference})", _("Merge requests")
 - page_description @merge_request.description_html
 - page_card_attributes @merge_request.card_attributes
-- suggest_changes_help_path = help_page_path('user/discussions/index.md', anchor: 'suggest-changes')
+- suggest_changes_help_path = help_page_path('user/project/merge_requests/reviews/suggestions.md')
 - number_of_pipelines = @pipelines.size
 - mr_action = j(params[:tab].presence || 'show')
 - add_page_specific_style 'page_bundles/merge_requests'

doc/development/code_review.md

@@ -387,7 +387,7 @@ If a merge request is fundamentally ready, but needs only trivial fixes (such as
 typos), consider demonstrating a [bias for
 action](https://about.gitlab.com/handbook/values/#bias-for-action) by making
 those changes directly without going back to the author. You can do this by
-using the [suggest changes](../user/discussions/index.md#suggest-changes) feature to apply
+using the [suggest changes](../user/project/merge_requests/reviews/suggestions.md) feature to apply
 your own suggestions to the merge request. Note that:
 
 - If the changes are not straightforward, please prefer allowing the author to make the change.

doc/user/admin_area/diff_limits.md

@@ -9,7 +9,7 @@ type: reference
 
 You can set a maximum size for display of diff files (patches).
 
-For details about diff files, [View changes between files](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-changes-between-file-versions).
+For details about diff files, [View changes between files](../project/merge_requests/reviews/index.md#view-changes-between-file-versions).
 
 ## Maximum diff patch size
 

doc/user/discussions/index.md

@@ -382,142 +382,6 @@ After you select one of the filters in a given issue or merge request, GitLab sa
 your preference, so that it persists when you visit the same page again
 from any device you're logged into.
 
-## Suggest Changes
-
-> - [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.
-> - [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 applied them.
-
-1. Choose a line of code to be changed, add a new comment, then click
-   on the **Insert suggestion** icon in the toolbar:
-
-   ![Add a new comment](img/suggestion_button_v13_9.png)
-
-1. In the comment, add your suggestion to the pre-populated code block:
-
-   ![Add a suggestion into a code block tagged properly](img/make_suggestion_v13_9.png)
-
-1. Click either **Start a review** or **Add to review** to add your comment to a [review](#merge-request-reviews), or **Add comment now** to add the comment to the thread immediately.
-
-   The Suggestion in the comment can be applied by the merge request author
-   directly from the merge request:
-
-   ![Apply suggestions](img/apply_suggestion_v13_9.png)
-
-1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9,
-   you can opt to add a custom commit message to describe your change. If you don't
-   specify it, the default commit message is used. It is not supported for [batch suggestions](#batch-suggestions).
-
-   ![Custom commit](img/custom_commit_v13_9.png)
-
-After the author applies a Suggestion, it is marked with the **Applied** label,
-the thread is automatically resolved, and GitLab creates a new commit
-and push the suggested change directly into the codebase in the merge request's
-branch. [Developer permission](../permissions.md) is required to do so.
-
-### Multi-line Suggestions
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10.
-
-Reviewers can also suggest changes to multiple lines with a single Suggestion
-within merge request diff threads by adjusting the range offsets. The
-offsets are relative to the position of the diff thread, and specify the
-range to be replaced by the suggestion when it is applied.
-
-![Multi-line suggestion syntax](img/multi-line-suggestion-syntax.png)
-
-In the example above, the Suggestion covers three lines above and four lines
-below the commented line. When applied, it would replace from 3 lines _above_
-to 4 lines _below_ the commented line, with the suggested change.
-
-![Multi-line suggestion preview](img/multi-line-suggestion-preview.png)
-
-NOTE:
-Suggestions covering multiple lines are limited to 100 lines _above_ and 100
-lines _below_ the commented diff line, allowing up to 200 changed lines per
-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.
-
-![A comment editor with a suggestion with a fenced code block](img/suggestion_code_block_editor_v12_8.png)
-
-![Output of a comment with a suggestion with a fenced code block](img/suggestion_code_block_output_v12_8.png)
-
-### Configure the commit message for applied Suggestions
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7.
-
-GitLab uses a default commit message
-when applying Suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)`
-
-For example, consider that a user applied 3 suggestions to 2 different files, the default commit message is: **Apply 3 suggestion(s) to 2 file(s)**
-
-These commit messages can be customized to follow any guidelines you might have. To do so, expand the **Merge requests**
-tab within your project's **General** settings and change the
-**Merge suggestions** text:
-
-![Custom commit message for applied Suggestions](img/suggestions_custom_commit_messages_v13_1.jpg)
-
-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` |
-| `%{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** |
-
-For example, to customize the commit message to output
-**Addresses user_1's review**, set the custom text to
-`Addresses %{username}'s review`.
-
-NOTE:
-Custom commit messages for each applied Suggestion is
-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.
-> - [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.
-
-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, click **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")
-
-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")
-
-1. To remove suggestions, click **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")
-
-1. Having added all the suggestions to your liking, when ready, click **Apply suggestions**:
-
-   ![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")
-
-WARNING:
-Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions.
-
 ## Start a thread by replying to a standard comment
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9

doc/user/project/merge_requests/creating_merge_requests.md

@@ -249,4 +249,4 @@ branch already exists, the patches are applied on top of it.
 
 ## Reviewing and managing Merge Requests
 
-Once you have submitted a merge request, it can be [reviewed and managed](reviewing_and_managing_merge_requests.md) through GitLab.
+Once you have submitted a merge request, it can be [reviewed and managed](reviews/index.md) through GitLab.

doc/user/project/merge_requests/getting_started.md

@@ -65,24 +65,24 @@ request's page at the top-right side:
 After you have created the merge request, you can also:
 
 - [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread.
-- [Perform inline code reviews](reviewing_and_managing_merge_requests.md#perform-inline-code-reviews).
+- [Perform inline code reviews](reviews/index.md#perform-inline-code-reviews).
 - Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)**
-- Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets).
-- Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps).
+- Preview continuous integration [pipelines on the merge request widget](reviews/index.md#pipeline-status-in-merge-requests-widgets).
+- Preview how your changes look directly on your deployed application with [Review Apps](reviews/index.md#live-preview-with-review-apps).
 - [Allow collaboration on merge requests across forks](allow_collaboration.md).
 - Perform a [Review](../../discussions/index.md#merge-request-reviews) to create multiple comments on a diff and publish them when you're ready.
-- Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI.
+- Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI.
 - Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking).
 
 Many of these can be set when pushing changes from the command line,
 with [Git push options](../push_options.md).
 
-See also other [features associated to merge requests](reviewing_and_managing_merge_requests.md#associated-features).
+See also other [features associated to merge requests](reviews/index.md#associated-features).
 
 ### Assignee
 
 Choose an assignee to designate someone as the person responsible
-for the first [review of the merge request](reviewing_and_managing_merge_requests.md).
+for the first [review of the merge request](reviews/index.md).
 Open the drop down box to search for the user you wish to assign,
 and the merge request is added to their
 [assigned merge request list](../../search/index.md#issues-and-merge-requests).

doc/user/project/merge_requests/index.md

@@ -72,6 +72,6 @@ Feature.disable(:mr_tabs_position)
 ## Related topics
 
 - [Create a merge request](creating_merge_requests.md)
-- [Review and manage merge requests](reviewing_and_managing_merge_requests.md)
+- [Review and manage merge requests](reviews/index.md)
 - [Authorization for merge requests](authorization_for_merge_requests.md)
 - [Testing and reports](testing_and_reports_in_merge_requests.md)

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

+---
+stage: Create
+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
+type: index, reference
+---
+
+# Suggest Changes
+
+> - [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.
+> - [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 applied them.
+
+1. Choose a line of code to be changed, add a new comment, then click
+   on the **Insert suggestion** icon in the toolbar:
+
+   ![Add a new comment](img/suggestion_button_v13_9.png)
+
+1. In the comment, add your suggestion to the pre-populated code block:
+
+   ![Add a suggestion into a code block tagged properly](img/make_suggestion_v13_9.png)
+
+1. Click either **Start a review** or **Add to review** to add your comment to a [review](index.md), or **Add comment now** to add the comment to the thread immediately.
+
+   The Suggestion in the comment can be applied by the merge request author
+   directly from the merge request:
+
+   ![Apply suggestions](img/apply_suggestion_v13_9.png)
+
+1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9,
+   you can opt to add a custom commit message to describe your change. If you don't
+   specify it, the default commit message is used. It is not supported for [batch suggestions](#batch-suggestions).
+
+   ![Custom commit](img/custom_commit_v13_9.png)
+
+After the author applies a Suggestion, it is marked with the **Applied** label,
+the thread is automatically resolved, and GitLab creates a new commit
+and push the suggested change directly into the codebase in the merge request's
+branch. [Developer permission](../../../permissions.md) is required to do so.
+
+## Multi-line Suggestions
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10.
+
+Reviewers can also suggest changes to multiple lines with a single Suggestion
+within merge request diff threads by adjusting the range offsets. The
+offsets are relative to the position of the diff thread, and specify the
+range to be replaced by the suggestion when it is applied.
+
+![Multi-line suggestion syntax](img/multi-line-suggestion-syntax.png)
+
+In the example above, the Suggestion covers three lines above and four lines
+below the commented line. When applied, it would replace from 3 lines _above_
+to 4 lines _below_ the commented line, with the suggested change.
+
+![Multi-line suggestion preview](img/multi-line-suggestion-preview.png)
+
+NOTE:
+Suggestions covering multiple lines are limited to 100 lines _above_ and 100
+lines _below_ the commented diff line, allowing up to 200 changed lines per
+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.
+
+![A comment editor with a suggestion with a fenced code block](img/suggestion_code_block_editor_v12_8.png)
+
+![Output of a comment with a suggestion with a fenced code block](img/suggestion_code_block_output_v12_8.png)
+
+## Configure the commit message for applied Suggestions
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7.
+
+GitLab uses a default commit message
+when applying Suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)`
+
+For example, consider that a user applied 3 suggestions to 2 different files, the default commit message is: **Apply 3 suggestion(s) to 2 file(s)**
+
+These commit messages can be customized to follow any guidelines you might have. To do so, expand the **Merge requests**
+tab within your project's **General** settings and change the
+**Merge suggestions** text:
+
+![Custom commit message for applied Suggestions](img/suggestions_custom_commit_messages_v13_1.jpg)
+
+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` |
+| `%{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** |
+
+For example, to customize the commit message to output
+**Addresses user_1's review**, set the custom text to
+`Addresses %{username}'s review`.
+
+NOTE:
+Custom commit messages for each applied Suggestion is
+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.
+> - [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.
+
+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, click **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")
+
+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")
+
+1. To remove suggestions, click **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")
+
+1. Having added all the suggestions to your liking, when ready, click **Apply suggestions**:
+
+   ![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")
+
+WARNING:
+Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions.

doc/user/project/settings/index.md

@@ -194,7 +194,7 @@ Set up your project's merge request settings:
 - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md).
 - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved).
 - Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch)
-- Configure [suggested changes commit messages](../../discussions/index.md#configure-the-commit-message-for-applied-suggestions)
+- Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions)
 - Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks.
 
 ### Service Desk