Merge branch '18608-lock-issues-v2' into 'master'

Resolve "Lock issue and merge request"

Closes #18608

See merge request gitlab-org/gitlab-ce!14531

9 files changed, 104 insertions, 5 deletions

diff --git a/doc/api/issues.md b/doc/api/issues.md
index cd2cfe8e430..ec8ff3cd3f3 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -110,7 +110,8 @@ Example response:
          "human_time_estimate": null,
          "human_total_time_spent": null
       },
-      "confidential": false
+      "confidential": false,
+      "discussion_locked": false
    }
 ]
 ```
@@ -216,7 +217,8 @@ Example response:
          "human_time_estimate": null,
          "human_total_time_spent": null
       },
-      "confidential": false
+      "confidential": false,
+      "discussion_locked": false
    }
 ]
 ```
@@ -323,7 +325,8 @@ Example response:
          "human_time_estimate": null,
          "human_total_time_spent": null
       },
-      "confidential": false
+      "confidential": false,
+      "discussion_locked": false
    }
 ]
 ```
@@ -407,6 +410,7 @@ Example response:
       "human_total_time_spent": null
    },
    "confidential": false,
+   "discussion_locked": false,
    "_links": {
       "self": "http://example.com/api/v4/projects/1/issues/2",
       "notes": "http://example.com/api/v4/projects/1/issues/2/notes",
@@ -482,6 +486,7 @@ Example response:
       "human_total_time_spent": null
    },
    "confidential": false,
+   "discussion_locked": false,
    "_links": {
       "self": "http://example.com/api/v4/projects/1/issues/2",
       "notes": "http://example.com/api/v4/projects/1/issues/2/notes",
@@ -515,6 +520,8 @@ PUT /projects/:id/issues/:issue_iid
 | `state_event`  | string  | no       | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it                      |
 | `updated_at`   | string  | no       | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) |
 | `due_date`     | string  | no       | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`                                           |
+| `discussion_locked` | boolean | no  | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. |
+
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close
@@ -558,6 +565,7 @@ Example response:
       "human_total_time_spent": null
    },
    "confidential": false,
+   "discussion_locked": false,
    "_links": {
       "self": "http://example.com/api/v4/projects/1/issues/2",
       "notes": "http://example.com/api/v4/projects/1/issues/2/notes",
@@ -657,6 +665,7 @@ Example response:
     "human_total_time_spent": null
   },
   "confidential": false,
+  "discussion_locked": false,
   "_links": {
     "self": "http://example.com/api/v4/projects/1/issues/2",
     "notes": "http://example.com/api/v4/projects/1/issues/2/notes",
@@ -735,6 +744,7 @@ Example response:
     "human_total_time_spent": null
   },
   "confidential": false,
+  "discussion_locked": false,
   "_links": {
     "self": "http://example.com/api/v4/projects/1/issues/2",
     "notes": "http://example.com/api/v4/projects/1/issues/2/notes",
@@ -765,6 +775,44 @@ POST /projects/:id/issues/:issue_iid/unsubscribe
 curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe
 ```
 
+Example response:
+
+```json
+{
+  "id": 93,
+  "iid": 12,
+  "project_id": 5,
+  "title": "Incidunt et rerum ea expedita iure quibusdam.",
+  "description": "Et cumque architecto sed aut ipsam.",
+  "state": "opened",
+  "created_at": "2016-04-05T21:41:45.217Z",
+  "updated_at": "2016-04-07T13:02:37.905Z",
+  "labels": [],
+  "milestone": null,
+  "assignee": {
+    "name": "Edwardo Grady",
+    "username": "keyon",
+    "id": 21,
+    "state": "active",
+    "avatar_url": "http://www.gravatar.com/avatar/3e6f06a86cf27fa8b56f3f74f7615987?s=80&d=identicon",
+    "web_url": "https://gitlab.example.com/keyon"
+  },
+  "author": {
+    "name": "Vivian Hermann",
+    "username": "orville",
+    "id": 11,
+    "state": "active",
+    "avatar_url": "http://www.gravatar.com/avatar/5224fd70153710e92fb8bcf79ac29d67?s=80&d=identicon",
+    "web_url": "https://gitlab.example.com/orville"
+  },
+  "subscribed": false,
+  "due_date": null,
+  "web_url": "http://example.com/example/example/issues/12",
+  "confidential": false,
+  "discussion_locked": false
+}
+```
+
 ## Create a todo
 
 Manually creates a todo for the current user on an issue. If
@@ -857,7 +905,8 @@ Example response:
     "downvotes": 0,
     "due_date": null,
     "web_url": "http://example.com/example/example/issues/110",
-    "confidential": false
+    "confidential": false,
+    "discussion_locked": false
   },
   "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/issues/10",
   "body": "Vel voluptas atque dicta mollitia adipisci qui at.",
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 63a5dd1445c..50a971102fb 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -201,6 +201,7 @@ Parameters:
     "should_remove_source_branch": true,
     "force_remove_source_branch": false,
     "web_url": "http://example.com/example/example/merge_requests/1",
+    "discussion_locked": false,
     "time_stats": {
       "time_estimate": 0,
       "total_time_spent": 0,
@@ -276,6 +277,7 @@ Parameters:
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
+  "discussion_locked": false,
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -387,6 +389,7 @@ Parameters:
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
+  "discussion_locked": false,
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -480,6 +483,7 @@ POST /projects/:id/merge_requests
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
+  "discussion_locked": false,
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -509,6 +513,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid
 | `labels`               | string  | no       | Labels for MR as a comma-separated list                                         |
 | `milestone_id`         | integer | no       | The ID of a milestone                                                           |
 | `remove_source_branch` | boolean | no       | Flag indicating if a merge request should remove the source branch when merging |
+| `discussion_locked`    | boolean | no       | Flag indicating if the merge request's discussion is locked. If the discussion is locked only project members can add, edit or resolve comments. |
 
 Must include at least one non-required attribute from above.
 
@@ -563,6 +568,7 @@ Must include at least one non-required attribute from above.
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
+  "discussion_locked": false,
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -667,6 +673,7 @@ Parameters:
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
+  "discussion_locked": false,
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -743,6 +750,7 @@ Parameters:
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
+  "discussion_locked": false,
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -1037,7 +1045,8 @@ Example response:
       "id": 14,
       "state": "active",
       "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon",
-      "web_url": "https://gitlab.example.com/francisca"
+      "web_url": "https://gitlab.example.com/francisca",
+      "discussion_locked": false
     },
     "assignee": {
       "name": "Dr. Gabrielle Strosin",
diff --git a/doc/user/discussions/img/discussion_lock_system_notes.png b/doc/user/discussions/img/discussion_lock_system_notes.png
new file mode 100644
index 00000000000..8e8e8e0bc3d
--- /dev/null
+++ b/doc/user/discussions/img/discussion_lock_system_notes.png
diff --git a/doc/user/discussions/img/lock_form_member.png b/doc/user/discussions/img/lock_form_member.png
new file mode 100644
index 00000000000..01c6308d24c
--- /dev/null
+++ b/doc/user/discussions/img/lock_form_member.png
diff --git a/doc/user/discussions/img/lock_form_non_member.png b/doc/user/discussions/img/lock_form_non_member.png
new file mode 100644
index 00000000000..3bb70b69580
--- /dev/null
+++ b/doc/user/discussions/img/lock_form_non_member.png
diff --git a/doc/user/discussions/img/turn_off_lock.png b/doc/user/discussions/img/turn_off_lock.png
new file mode 100644
index 00000000000..dd05b398a8b
--- /dev/null
+++ b/doc/user/discussions/img/turn_off_lock.png
diff --git a/doc/user/discussions/img/turn_on_lock.png b/doc/user/discussions/img/turn_on_lock.png
new file mode 100644
index 00000000000..9597da4e14d
--- /dev/null
+++ b/doc/user/discussions/img/turn_on_lock.png
diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md
index efea99eb120..ab46befb91c 100644
--- a/doc/user/discussions/index.md
+++ b/doc/user/discussions/index.md
@@ -153,12 +153,52 @@ comments in greater detail.
 
 ![Discussion comment](img/discussion_comment.png)
 
+## Locking discussions
+
+> [Introduced][ce-14531] in GitLab 10.1.
+
+There might be some cases where a discussion is better off if it's locked down.
+For example:
+
+- Discussions that are several years old and the issue/merge request is closed,
+  but people continue to try to resurrect the discussion.
+- Discussions where someone or a group of people are trolling, are abusive, or
+  in-general are causing the discussion to be unproductive.
+
+In locked discussions, only team members can write new comments and edit the old
+ones.
+
+To lock or unlock a discussion, you need to have at least Master [permissions]:
+
+1. Find the "Lock" section in the sidebar and click **Edit**
+1. In the dialog that will appear, you can choose to turn on or turn off the
+   discussion lock
+1. Optionally, leave a comment to explain your reasoning behind that action
+
+| Turn off discussion lock | Turn on discussion lock |
+| :-----------: | :----------: |
+| ![Turn off discussion lock](img/turn_off_lock.png) | ![Turn on discussion lock](img/turn_on_lock.png) |
+
+Every change is indicated by a system note in the issue's or merge request's
+comments.
+
+![Discussion lock system notes](img/discussion_lock_system_notes.png)
+
+Once an issue or merge request is locked, project members can see the indicator
+in the comment area, whereas non project members can only see the information
+that the discussion is locked.
+
+| Team member | Not a member |
+| :-----------: | :----------: |
+| ![Comment form member](img/lock_form_member.png) | ![Comment form non-member](img/lock_form_non_member.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
 [ce-7180]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7180
 [ce-8266]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8266
 [ce-14053]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14053
+[ce-14531]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14531
 [resolve-discussion-button]: img/resolve_discussion_button.png
 [resolve-comment-button]: img/resolve_comment_button.png
 [discussion-view]: img/discussion_view.png
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 8ff7b483c2a..be72d42625a 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -25,6 +25,7 @@ The following table depicts the various user permission levels in a project.
 | Create confidential issue             | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
 | View confidential issues              | (✓) [^2] | ✓          | ✓           | ✓        | ✓      |
 | Leave comments                        | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
+| Lock comments                         |         |            |             | ✓        | ✓      |
 | See a list of jobs                    | ✓ [^3]  | ✓          | ✓           | ✓        | ✓      |
 | See a job   log                       | ✓ [^3]  | ✓          | ✓           | ✓        | ✓      |
 | Download and browse job artifacts     | ✓ [^3]  | ✓          | ✓           | ✓        | ✓      |