feat(comments): add deep link API route and release notes

Author: palkerecsenyi

docs/reference/rest_api_requests.md

@@ -601,7 +601,8 @@ Content-Type: application/json
         "created_by": {"user": "1"},
         "id": "{comment_id}",
         "links": {
-          "self": "{scheme+hostname}/api/requests/{rquest_id}/comments/{comment_id}"
+          "self": "{scheme+hostname}/api/requests/{request_id}/comments/{comment_id}"
+          "self_html": "{scheme+hostname}/me/requests/{request_id}#commentevent-{comment_id}"
         },
         "payload": {
           "content": "I would use these subject terms to align this record and the other one with others in the community.",
@@ -615,6 +616,8 @@ Content-Type: application/json
     ],
     "total": 2
   },
+  "sortBy": "oldest",
+  "page": 1,
   "links": {
     "self": "{scheme+hostname}/api/requests/{request_id}/timeline?page=1&size=25&sort=oldest"
   }
@@ -624,3 +627,68 @@ Content-Type: application/json
 !!! info "Advanced timeline search"
 
     The timeline endpoint can be searched, sorted, filtered, paginated etc., like any other InvenioRDM search endpoint.
+
+### Get the timeline focused on a specific event
+
+`GET /api/requests/{request_id}/timeline_focused?focus_event_id={event_id}`
+
+Same as above, except the page containing the specified event is returned.
+If the event is not found or does not belong to the request, the first page of events is instead returned.
+The page number used is returned as the `"page"` key of the response.
+
+The `"self_html"` link of the returned items is a pagination-aware deep link that causes the event to be scrolled to and highlighted
+when the request page is opened (only if the event is of type `CommentEventType`).
+
+The events are always sorted oldest-to-newest.
+
+**Parameters**
+
+| Name                    | Type    | Location | Description                                                                          |
+| ----------------------- | ------  | -------- | ------------------------------------------------------------------------------------ |
+| `request_id`       | string  | path     | The request's public identifier.                                                     |
+| `focus_event_id`   | string  | query    | The events's public identifier.                                                      |
+| `size`                  | integer | query    | Specify number of items in the results page (default: 10).                           |
+| `accept`                | string  | header   | - `application/json` (default)<br />- `application/vnd.inveniordm.v1+json` (not yet) |
+
+**Request**
+
+```http
+GET /api/requests/{request_id}/timeline_focused?focus_event_id={event_id} HTTP/1.1
+```
+
+**Response**
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "hits": {
+    "hits": [
+      {
+        "created": "2020-11-27 10:52:23.945755",
+        "created_by": {"user": "1"},
+        "id": "{comment_id}",
+        "links": {
+          "self": "{scheme+hostname}/api/requests/{request_id}/comments/{comment_id}"
+          "self_html": "{scheme+hostname}/me/requests/{request_id}#commentevent-{comment_id}"
+        },
+        "payload": {
+          "content": "I would use these subject terms to align this record and the other one with others in the community.",
+          "format": "html"
+        },
+        "revision_id": 2,
+        "type": "C",
+        "updated": "2020-11-27 10:55:23.969244",
+      },
+      ...
+    ],
+    "total": 2
+  },
+  "sortBy": "oldest",
+  "page": 1,
+  "links": {
+    "self": "{scheme+hostname}/api/requests/{request_id}/timeline?page=1&size=25&sort=oldest"
+  }
+}
+```

docs/releases/vNext/imgs/comment-deep-link.png

@@ -25,7 +25,22 @@ You can now allow users to delete, or request deletion of, their own records in
 
 This feature is also [highly customisable](../../operate/customize/record_deletion.md)! You can introduce deletion policies based on the resource type, community role, file type or any other criteria you require. Additionally, you can prevent extraneous record deletion by adding a deletion checklist. This allows you to suggest how the user can fix the problem in the correct way instead of deleting the record.
 
-#### New Web Archive previewer
+### Request commenting enhancements
+
+We've introduced a number of exciting new features to improve the commenting experience on requests, which are currently used across InvenioRDM
+for a range of purposes such as community record submission.
+
+#### Deep links
+
+You can now copy a link to a comment directly, allowing for easy and precise sharing.
+When opened, the link will take the user to the comment and highlight it, regardless of which page it's on.
+
+To use deep links, simply click the "Copy link" button on a comment:
+
+![Comment with the "copy link" button](imgs/comment-deep-link.png)
+
+
+### New Web Archive previewer
 
 https://github.com/inveniosoftware/invenio-previewer/pull/224