1 files changed, 42 insertions, 12 deletions

diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md
index bf3e907bd24..7d0413a1f1b 100644
--- a/doc/user/discussions/index.md
+++ b/doc/user/discussions/index.md
@@ -44,7 +44,7 @@ Thread resolution helps keep track of progress during planning or code review.
 Every standard comment or thread in merge requests, commits, commit diffs, and
 snippets is initially displayed as unresolved. They can then be individually resolved by anyone
 with at least Developer access to the project or by the author of the change being reviewed.
-If the thread has been resolved and a non-member unresolves their own response,
+If the thread has been resolved and a non-member un-resolves their own response,
 this will also unresolve the discussion thread.
 If the non-member then resolves this same response, this will resolve the discussion thread.
 
@@ -115,7 +115,7 @@ are resolved](#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolve
 there will be an **open an issue to resolve them later** link in the merge
 request widget.
 
-![Link in merge request widget](img/resolve_thread_open_issue.png)
+![Link in merge request widget](img/resolve_thread_open_issue_v13_9.png)
 
 This will prepare an issue with its content referring to the merge request and
 the unresolved threads.
@@ -161,7 +161,7 @@ box and hit **Save** for the changes to take effect.
 From now on, you will not be able to merge from the UI until all threads
 are resolved.
 
-![Only allow merge if all the threads are resolved message](img/resolve_thread_open_issue.png)
+![Only allow merge if all the threads are resolved message](img/resolve_thread_open_issue_v13_9.png)
 
 ### Automatically resolve merge request diff threads when they become outdated
 
@@ -284,7 +284,7 @@ Additionally, locked issues and merge requests can not be reopened.
 ## Merge Request Reviews
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.4.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Core in 13.1.
+> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1.
 
 When looking at a Merge Request diff, you are able to start a review.
 This allows you to create comments inside a Merge Request that are **only visible to you** until published,
@@ -370,13 +370,17 @@ From a merge request's **Discussion** tab, or from an epic/issue overview, find
 
 ![Notes filters dropdown options](img/index_notes_filters.png)
 
-Once you select one of the filters in a given issue or MR, GitLab will save
+After you select one of the filters in a given issue or MR, GitLab will save
 your preference, so that it will persist 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.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6.
+> - Custom commit messages for suggestions were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9.
+> - Custom commit messages for suggestions is disabled on GitLab.com and not recommended for production use.
+> - Custom commit messages for suggestions was deployed behind a [feature flag](../feature_flags.md), disabled by default.
+> - To use custom commit messages for suggestions in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-custom-commit-messages-for-suggestions). **(FREE SELF)**
 
 As a reviewer, you're able to suggest code changes with a simple
 Markdown syntax in Merge Request Diff threads. Then, the
@@ -388,24 +392,50 @@ 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_v12_7.png)
+   ![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_v12_7.png)
+   ![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_v12_7.png)
+   ![Apply suggestions](img/apply_suggestion_v13_9.png)
 
-Once the author applies a Suggestion, it will be marked with the **Applied** label,
+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 will be used. Note that [this feature may not be available to you](#enable-or-disable-custom-commit-messages-for-suggestions). 
+   Also, it is not supported for [batch suggestions](#batch-suggestions).
+
+   ![Custom commit](img/custom_commit_v13_9.png)
+
+After the author applies a Suggestion, it will be marked with the **Applied** label,
 the thread will be automatically resolved, and GitLab will create 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.
 
+### Enable or disable Custom commit messages for suggestions **(FREE SELF)**
+
+Custom commit messages for suggestions is under development and not ready for production use. It is
+deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can enable it.
+
+To enable custom commit messages for suggestions:
+
+```ruby
+Feature.enable(:suggestions_custom_commit)
+```
+
+To disable custom commit messages for suggestions:
+
+```ruby
+Feature.disable(:suggestions_custom_commit)
+```
+
 ### Multi-line Suggestions
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10.
@@ -501,7 +531,7 @@ to your branch to address your reviewers' requests.
 
    ![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")
 
-#### Enable or disable Batch Suggestions **(CORE ONLY)**
+#### Enable or disable Batch Suggestions **(FREE SELF)**
 
 Batch Suggestions is
 deployed behind a feature flag that is **enabled by default**.
@@ -537,7 +567,7 @@ Clicking on the **Reply to comment** button will bring the reply area into focus
 ![Reply to comment feature](img/reply_to_comment.gif)
 
 Replying to a non-thread comment will convert the non-thread comment to a
-thread once the reply is submitted. This conversion is considered an edit
+thread after the reply is submitted. This conversion is considered an edit
 to the original comment, so a note about when it was last edited will appear underneath it.
 
 This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are