add documentationdocs/commit-diff-discussions-in-mr-context

4 files changed, 39 insertions, 0 deletions

diff --git a/doc/user/discussions/img/commit-comment-mr-context.png b/doc/user/discussions/img/commit-comment-mr-context.png
new file mode 100644
index 00000000000..b363e0035e8
--- /dev/null
+++ b/doc/user/discussions/img/commit-comment-mr-context.png
diff --git a/doc/user/discussions/img/commit-comment-mr-discussions-tab.png b/doc/user/discussions/img/commit-comment-mr-discussions-tab.png
new file mode 100644
index 00000000000..2b06cdcc055
--- /dev/null
+++ b/doc/user/discussions/img/commit-comment-mr-discussions-tab.png
diff --git a/doc/user/discussions/img/merge-request-commits-tab.png b/doc/user/discussions/img/merge-request-commits-tab.png
new file mode 100644
index 00000000000..41a3648f390
--- /dev/null
+++ b/doc/user/discussions/img/merge-request-commits-tab.png
diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md
index 2206b2860f4..b8f4f0ab5e3 100644
--- a/doc/user/discussions/index.md
+++ b/doc/user/discussions/index.md
@@ -221,6 +221,44 @@ edit existing comments. Non-team members are restricted from adding or editing c
 | :-----------: | :----------: |
 | ![Comment form member](img/lock_form_member.png) | ![Comment form non-member](img/lock_form_non_member.png) |
 
+## Commit discussions
+
+> **Note:** Discussions created this way will be lost if the commit ID changes.
+
+Navigating to a commit will present you the commit page, where you may add comments and
+discussions threads to a particular commit.
+
+### In the context of a merge request
+
+> [Introduced][ce-12148] in GitLab 10.3
+
+> **Note:** Only **commit diff** discussions are currently supported.
+
+> **Note:** Discussions created this way will only appear in the original merge request.
+
+For reviewers with commit-based workflow, it may be useful to add discussions to
+specific commit diffs in the context of a merge request. These discussions will persist
+through a commit ID change:
+
+- Through a force-push after a rebase
+- After amending a commit
+
+To create a commit diff discussion, go to the merge request _Commits_ tab.
+A list of commits that consitute the merge request will be shown. 
+
+![Merge request commits tab](img/merge-request-commits-tab.png)
+
+GitLab will also automatically convert links of commit reference in the 
+context of the current merge request when they are found in discussions.
+
+Navigating to a commit will bring you to the _Changes_ tab, where you will only be presented diffs from the selected commit. 
+
+![Commit diff discussion in merge request context](img/commit-comment-mr-context.png)
+
+Discussions created this way will be shown in the merge request's _Discussions_ tab and are resolvable.
+
+![Merge request Discussions tab](img/commit-comment-mr-discussions-tab.png)
+
 [ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022
 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125
 [ce-7527]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7527
@@ -229,6 +267,7 @@ edit existing comments. Non-team members are restricted from adding or editing c
 [ce-14053]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14053
 [ce-14061]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14061
 [ce-14531]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14531
+[ce-12148]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12148
 [resolve-discussion-button]: img/resolve_discussion_button.png
 [resolve-comment-button]: img/resolve_comment_button.png
 [discussion-view]: img/discussion_view.png