Add latest changes from gitlab-org/gitlab@master

3 files changed, 226 insertions, 14 deletions

diff --git a/doc/api/epics.md b/doc/api/epics.md
index 531c75fd8c5..4b20534eeed 100644
--- a/doc/api/epics.md
+++ b/doc/api/epics.md
@@ -29,6 +29,14 @@ are paginated.
 
 Read more on [pagination](README.md#pagination).
 
+CAUTION: **Deprecation**
+> `reference` attribute in response is deprecated in favour of `references`.
+> Introduced [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/merge_requests/20354)
+
+NOTE: **Note**
+> `references.relative` is relative to the group that the epic is being requested. When epic is fetched from its origin group
+> `relative` format would be the same as `short` format and when requested cross groups it is expected to be the same as `full` format.
+
 ## List epics for a group
 
 Gets all epics of the requested group and its subgroups.
@@ -73,6 +81,51 @@ Example response:
   "state": "opened",
   "web_url": "http://localhost:3001/groups/test/-/epics/4",
   "reference": "&4",
+  "references": {
+    "short": "&4",
+    "relative": "&4",
+    "full": "test&4"
+  },
+  "author": {
+    "id": 10,
+    "name": "Lu Mayer",
+    "username": "kam",
+    "state": "active",
+    "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
+    "web_url": "http://localhost:3001/kam"
+  },
+  "start_date": null,
+  "start_date_is_fixed": false,
+  "start_date_fixed": null,
+  "start_date_from_milestones": null,       //deprecated in favor of start_date_from_inherited_source
+  "start_date_from_inherited_source": null,
+  "end_date": "2018-07-31",                 //deprecated in favor of due_date
+  "due_date": "2018-07-31",
+  "due_date_is_fixed": false,
+  "due_date_fixed": null,
+  "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source
+  "due_date_from_inherited_source": "2018-07-31",
+  "created_at": "2018-07-17T13:36:22.770Z",
+  "updated_at": "2018-07-18T12:22:05.239Z",
+  "closed_at": "2018-08-18T12:22:05.239Z",
+  "labels": [],
+  "upvotes": 4,
+  "downvotes": 0
+  },
+  {
+  "id": 50,
+  "iid": 35,
+  "group_id": 17,
+  "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
+  "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
+  "state": "opened",
+  "web_url": "http://localhost:3001/groups/test/sample/-/epics/4",
+  "reference": "&4",
+  "references": {
+    "short": "&4",
+    "relative": "sample&4",
+    "full": "test/sample&4"
+  },
   "author": {
     "id": 10,
     "name": "Lu Mayer",
@@ -131,6 +184,11 @@ Example response:
   "state": "opened",
   "web_url": "http://localhost:3001/groups/test/-/epics/5",
   "reference": "&5",
+  "references": {
+    "short": "&5",
+    "relative": "&5",
+    "full": "test&5"
+  },
   "author":{
     "id": 7,
     "name": "Pamella Huel",
@@ -199,8 +257,13 @@ Example response:
   "title": "Epic",
   "description": "Epic description",
   "state": "opened",
-  "web_url": "http://localhost:3001/groups/test/-/epics/5",
+  "web_url": "http://localhost:3001/groups/test/-/epics/6",
   "reference": "&6",
+  "references": {
+    "short": "&6",
+    "relative": "&6",
+    "full": "test&6"
+  },
   "author": {
     "name" : "Alexandra Bashirian",
     "avatar_url" : null,
@@ -269,8 +332,13 @@ Example response:
   "title": "New Title",
   "description": "Epic description",
   "state": "opened",
-  "web_url": "http://localhost:3001/groups/test/-/epics/5",
+  "web_url": "http://localhost:3001/groups/test/-/epics/6",
   "reference": "&6",
+  "references": {
+    "short": "&6",
+    "relative": "&6",
+    "full": "test&6"
+  },
   "author": {
     "name" : "Alexandra Bashirian",
     "avatar_url" : null,
@@ -372,6 +440,13 @@ Example response:
       "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",
       "web_url": "http://localhost:3001/arnita"
     },
+    "web_url": "http://localhost:3001/groups/test/-/epics/5",
+    "reference": "&5",
+    "references": {
+      "short": "&5",
+      "relative": "&5",
+      "full": "test&5"
+    },
     "start_date": null,
     "end_date": null,
     "created_at": "2018-01-21T06:21:13.165Z",
diff --git a/doc/api/issues.md b/doc/api/issues.md
index fe551cfb397..383d190a045 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -12,6 +12,14 @@ are paginated.
 
 Read more on [pagination](README.md#pagination).
 
+CAUTION: **Deprecation**
+> `reference` attribute in response is deprecated in favour of `references`.
+> Introduced [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/merge_requests/20354)
+
+NOTE: **Note**
+> `references.relative` is relative to the group / project that the issue is being requested. When issue is fetched from its project
+> `relative` format would be the same as `short` format and when requested across groups / projects it is expected to be the same as `full` format.
+
 ## List issues
 
 Get all issues the authenticated user has access to. By default it
@@ -121,7 +129,12 @@ Example response:
       "merge_requests_count": 0,
       "user_notes_count": 1,
       "due_date": "2016-07-22",
-      "web_url": "http://example.com/example/example/issues/6",
+      "web_url": "http://example.com/my-group/my-project/issues/6",
+      "references": {
+        "short": "#6",
+        "relative": "my-group/my-project#6",
+        "full": "my-group/my-project#6"
+      },
       "time_stats": {
          "time_estimate": 0,
          "total_time_spent": 0,
@@ -270,7 +283,12 @@ Example response:
       "closed_by" : null,
       "user_notes_count": 1,
       "due_date": null,
-      "web_url": "http://example.com/example/example/issues/1",
+      "web_url": "http://example.com/my-group/my-project/issues/1",
+      "references": {
+        "short": "#1",
+        "relative": "my-project#1",
+        "full": "my-group/my-project#1"
+      },
       "time_stats": {
          "time_estimate": 0,
          "total_time_spent": 0,
@@ -426,7 +444,12 @@ Example response:
       },
       "user_notes_count": 1,
       "due_date": "2016-07-22",
-      "web_url": "http://example.com/example/example/issues/1",
+      "web_url": "http://example.com/my-group/my-project/issues/1",
+      "references": {
+        "short": "#1",
+        "relative": "#1",
+        "full": "my-group/my-project#1"
+      },
       "time_stats": {
          "time_estimate": 0,
          "total_time_spent": 0,
@@ -543,7 +566,12 @@ Example response:
    "subscribed": false,
    "user_notes_count": 1,
    "due_date": null,
-   "web_url": "http://example.com/example/example/issues/1",
+   "web_url": "http://example.com/my-group/my-project/issues/1",
+   "references": {
+     "short": "#1",
+     "relative": "#1",
+     "full": "my-group/my-project#1"
+   },
    "time_stats": {
       "time_estimate": 0,
       "total_time_spent": 0,
@@ -668,7 +696,12 @@ Example response:
    "subscribed" : true,
    "user_notes_count": 0,
    "due_date": null,
-   "web_url": "http://example.com/example/example/issues/14",
+   "web_url": "http://example.com/my-group/my-project/issues/14",
+   "references": {
+     "short": "#14",
+     "relative": "#14",
+     "full": "my-group/my-project#14"
+   },
    "time_stats": {
       "time_estimate": 0,
       "total_time_spent": 0,
@@ -778,7 +811,12 @@ Example response:
    "subscribed" : true,
    "user_notes_count": 0,
    "due_date": "2016-07-22",
-   "web_url": "http://example.com/example/example/issues/15",
+   "web_url": "http://example.com/my-group/my-project/issues/15",
+   "references": {
+     "short": "#15",
+     "relative": "#15",
+     "full": "my-group/my-project#15"
+   },
    "time_stats": {
       "time_estimate": 0,
       "total_time_spent": 0,
@@ -900,7 +938,12 @@ Example response:
     "web_url": "https://gitlab.example.com/solon.cremin"
   },
   "due_date": null,
-  "web_url": "http://example.com/example/example/issues/11",
+  "web_url": "http://example.com/my-group/my-project/issues/11",
+  "references": {
+    "short": "#11",
+    "relative": "#11",
+    "full": "my-group/my-project#11"
+  },
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -1001,7 +1044,12 @@ Example response:
     "web_url": "https://gitlab.example.com/solon.cremin"
   },
   "due_date": null,
-  "web_url": "http://example.com/example/example/issues/11",
+  "web_url": "http://example.com/my-group/my-project/issues/11",
+  "references": {
+    "short": "#11",
+    "relative": "#11",
+    "full": "my-group/my-project#11"
+  },
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -1095,7 +1143,12 @@ Example response:
   },
   "subscribed": false,
   "due_date": null,
-  "web_url": "http://example.com/example/example/issues/12",
+  "web_url": "http://example.com/my-group/my-project/issues/12",
+  "references": {
+    "short": "#12",
+    "relative": "#12",
+    "full": "my-group/my-project#12"
+  },
   "confidential": false,
   "discussion_locked": false,
   "task_completion_status":{
@@ -1197,7 +1250,12 @@ Example response:
     "downvotes": 0,
     "merge_requests_count": 0,
     "due_date": null,
-    "web_url": "http://example.com/example/example/issues/110",
+    "web_url": "http://example.com/my-group/my-project/issues/10",
+    "references": {
+      "short": "#10",
+      "relative": "#10",
+      "full": "my-group/my-project#10"
+    },
     "confidential": false,
     "discussion_locked": false,
     "task_completion_status":{
@@ -1436,6 +1494,11 @@ Example response:
     "force_remove_source_branch": false,
     "reference": "!11",
     "web_url": "https://gitlab.example.com/twitter/flight/merge_requests/4",
+    "references": {
+      "short": "!4",
+      "relative": "!4",
+      "full": "twitter/flight!4"
+    },
     "time_stats": {
       "time_estimate": 0,
       "total_time_spent": 0,
@@ -1566,6 +1629,12 @@ Example response:
     "should_remove_source_branch": null,
     "force_remove_source_branch": false,
     "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/merge_requests/6432",
+    "reference": "!6432",
+    "references": {
+      "short": "!6432",
+      "relative": "!6432",
+      "full": "gitlab-org/gitlab-test!6432"
+    },
     "time_stats": {
       "time_estimate": 0,
       "total_time_spent": 0,
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 541aa03450f..d17db8deeb2 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -2,6 +2,14 @@
 
 Every API call to merge requests must be authenticated.
 
+CAUTION: **Deprecation**
+> `reference` attribute in response is deprecated in favour of `references`.
+> Introduced [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/merge_requests/20354)
+
+NOTE: **Note**
+> `references.relative` is relative to the group / project that the merge request is being requested. When merge request is fetched from its project
+> `relative` format would be the same as `short` format and when requested across groups / projects it is expected to be the same as `full` format.
+
 ## List merge requests
 
 > [Introduced][ce-13060] in GitLab 9.5.
@@ -134,6 +142,11 @@ Parameters:
     "allow_collaboration": false,
     "allow_maintainer_to_push": false,
     "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+    "references": {
+      "short": "!1",
+      "relative": "my-group/my-project!1",
+      "full": "my-group/my-project!1"
+    },
     "time_stats": {
       "time_estimate": 0,
       "total_time_spent": 0,
@@ -296,6 +309,11 @@ Parameters:
     "allow_collaboration": false,
     "allow_maintainer_to_push": false,
     "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+    "references": {
+      "short": "!1",
+      "relative": "!1",
+      "full": "my-group/my-project!1"
+    },
     "time_stats": {
       "time_estimate": 0,
       "total_time_spent": 0,
@@ -448,6 +466,11 @@ Parameters:
     "should_remove_source_branch": true,
     "force_remove_source_branch": false,
     "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+    "references": {
+      "short": "!1",
+      "relative": "my-project!1",
+      "full": "my-group/my-project!1"
+    },
     "time_stats": {
       "time_estimate": 0,
       "total_time_spent": 0,
@@ -574,6 +597,11 @@ Parameters:
   "allow_collaboration": false,
   "allow_maintainer_to_push": false,
   "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+  "references": {
+    "short": "!1",
+    "relative": "!1",
+    "full": "my-group/my-project!1"
+  },
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -779,7 +807,12 @@ Parameters:
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "squash": false,
-  "web_url": "http://example.com/example/example/merge_requests/1",
+  "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+  "references": {
+    "short": "!1",
+    "relative": "!1",
+    "full": "my-group/my-project!1"
+  },
   "discussion_locked": false,
   "time_stats": {
     "time_estimate": 0,
@@ -989,6 +1022,11 @@ order for it to take effect:
   "allow_collaboration": false,
   "allow_maintainer_to_push": false,
   "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+  "references": {
+    "short": "!1",
+    "relative": "!1",
+    "full": "my-group/my-project!1"
+  },
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -1143,6 +1181,11 @@ Must include at least one non-required attribute from above.
   "allow_collaboration": false,
   "allow_maintainer_to_push": false,
   "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+  "references": {
+    "short": "!1",
+    "relative": "!1",
+    "full": "my-group/my-project!1"
+  },
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -1313,6 +1356,11 @@ Parameters:
   "allow_collaboration": false,
   "allow_maintainer_to_push": false,
   "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+  "references": {
+    "short": "!1",
+    "relative": "!1",
+    "full": "my-group/my-project!1"
+  },
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -1486,6 +1534,11 @@ Parameters:
   "allow_collaboration": false,
   "allow_maintainer_to_push": false,
   "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+  "references": {
+    "short": "!1",
+    "relative": "!1",
+    "full": "my-group/my-project!1"
+  },
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -1772,6 +1825,11 @@ Example response:
   "allow_collaboration": false,
   "allow_maintainer_to_push": false,
   "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+  "references": {
+    "short": "!1",
+    "relative": "!1",
+    "full": "my-group/my-project!1"
+  },
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -1918,6 +1976,11 @@ Example response:
   "allow_collaboration": false,
   "allow_maintainer_to_push": false,
   "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
+  "references": {
+    "short": "!1",
+    "relative": "!1",
+    "full": "my-group/my-project!1"
+  },
   "time_stats": {
     "time_estimate": 0,
     "total_time_spent": 0,
@@ -2078,7 +2141,12 @@ Example response:
     "should_remove_source_branch": true,
     "force_remove_source_branch": false,
     "squash": false,
-    "web_url": "http://example.com/example/example/merge_requests/1"
+    "web_url": "http://example.com/my-group/my-project/merge_requests/1",
+    "references": {
+      "short": "!1",
+      "relative": "!1",
+      "full": "my-group/my-project!1"
+    },
   },
   "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/merge_requests/7",
   "body": "Et voluptas laudantium minus nihil recusandae ut accusamus earum aut non.",