Merge branch 'master' into 38464-k8s-apps

8 files changed, 75 insertions, 15 deletions

diff --git a/doc/api/custom_attributes.md b/doc/api/custom_attributes.md
index 8b26f7093ab..91d1b0e1520 100644
--- a/doc/api/custom_attributes.md
+++ b/doc/api/custom_attributes.md
@@ -2,17 +2,22 @@
 
 Every API call to custom attributes must be authenticated as administrator.
 
+Custom attributes are currently available on users, groups, and projects,
+which will be referred to as "resource" in this documentation.
+
 ## List custom attributes
 
-Get all custom attributes on a user.
+Get all custom attributes on a resource.
 
 ```
 GET /users/:id/custom_attributes
+GET /groups/:id/custom_attributes
+GET /projects/:id/custom_attributes
 ```
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a user |
+| `id` | integer | yes | The ID of a resource |
 
 ```bash
 curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/42/custom_attributes
@@ -35,15 +40,17 @@ Example response:
 
 ## Single custom attribute
 
-Get a single custom attribute on a user.
+Get a single custom attribute on a resource.
 
 ```
 GET /users/:id/custom_attributes/:key
+GET /groups/:id/custom_attributes/:key
+GET /projects/:id/custom_attributes/:key
 ```
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a user |
+| `id` | integer | yes | The ID of a resource |
 | `key` | string | yes | The key of the custom attribute |
 
 ```bash
@@ -61,16 +68,18 @@ Example response:
 
 ## Set custom attribute
 
-Set a custom attribute on a user. The attribute will be updated if it already exists,
+Set a custom attribute on a resource. The attribute will be updated if it already exists,
 or newly created otherwise.
 
 ```
 PUT /users/:id/custom_attributes/:key
+PUT /groups/:id/custom_attributes/:key
+PUT /projects/:id/custom_attributes/:key
 ```
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a user |
+| `id` | integer | yes | The ID of a resource |
 | `key` | string | yes | The key of the custom attribute |
 | `value` | string | yes | The value of the custom attribute |
 
@@ -89,15 +98,17 @@ Example response:
 
 ## Delete custom attribute
 
-Delete a custom attribute on a user.
+Delete a custom attribute on a resource.
 
 ```
 DELETE /users/:id/custom_attributes/:key
+DELETE /groups/:id/custom_attributes/:key
+DELETE /projects/:id/custom_attributes/:key
 ```
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a user |
+| `id` | integer | yes | The ID of a resource |
 | `key` | string | yes | The key of the custom attribute |
 
 ```bash
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 99d200c9c93..16db9c2f259 100644
--- a/doc/api/groups.md
+++ b/doc/api/groups.md
@@ -74,6 +74,12 @@ GET /groups?statistics=true
 
 You can search for groups by name or path, see below.
 
+You can filter by [custom attributes](custom_attributes.md) with:
+
+```
+GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value
+```
+
 ## List a group's projects
 
 Get a list of projects in this group. When accessed without authentication, only
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 50a971102fb..6de460f2778 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -15,6 +15,11 @@ given state (`opened`, `closed`, or `merged`) or all of them (`all`).
 The pagination parameters `page` and `per_page` can be used to
 restrict the list of merge requests.
 
+**Note**: the `changes_count` value in the response is a string, not an
+integer. This is because when an MR has too many changes to display and store,
+it will be capped at 1,000. In that case, the API will return the string
+`"1000+"` for the changes count.
+
 ```
 GET /merge_requests
 GET /merge_requests?state=opened
@@ -92,6 +97,7 @@ Parameters:
     "sha": "8888888888888888888888888888888888888888",
     "merge_commit_sha": null,
     "user_notes_count": 1,
+    "changes_count": "1",
     "should_remove_source_branch": true,
     "force_remove_source_branch": false,
     "web_url": "http://example.com/example/example/merge_requests/1",
@@ -130,6 +136,11 @@ will be the same. In the case of a merge request from a fork,
 `target_project_id` and `project_id` will be the same and
 `source_project_id` will be the fork project's ID.
 
+**Note**: the `changes_count` value in the response is a string, not an
+integer. This is because when an MR has too many changes to display and store,
+it will be capped at 1,000. In that case, the API will return the string
+`"1000+"` for the changes count.
+
 Parameters:
 
 | Attribute           | Type           | Required | Description                                                                                                                    |
@@ -198,6 +209,7 @@ Parameters:
     "sha": "8888888888888888888888888888888888888888",
     "merge_commit_sha": null,
     "user_notes_count": 1,
+    "changes_count": "1",
     "should_remove_source_branch": true,
     "force_remove_source_branch": false,
     "web_url": "http://example.com/example/example/merge_requests/1",
@@ -274,6 +286,7 @@ Parameters:
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": "9999999999999999999999999999999999999999",
   "user_notes_count": 1,
+  "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
@@ -386,6 +399,7 @@ Parameters:
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
   "user_notes_count": 1,
+  "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
@@ -480,6 +494,7 @@ POST /projects/:id/merge_requests
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
   "user_notes_count": 0,
+  "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
@@ -565,6 +580,7 @@ Must include at least one non-required attribute from above.
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
   "user_notes_count": 1,
+  "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
@@ -670,6 +686,7 @@ Parameters:
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": "9999999999999999999999999999999999999999",
   "user_notes_count": 1,
+  "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
@@ -747,6 +764,7 @@ Parameters:
   "sha": "8888888888888888888888888888888888888888",
   "merge_commit_sha": null,
   "user_notes_count": 1,
+  "changes_count": "1",
   "should_remove_source_branch": true,
   "force_remove_source_branch": false,
   "web_url": "http://example.com/example/example/merge_requests/1",
@@ -822,7 +840,8 @@ Example response when the GitLab issue tracker is used:
       "created_at" : "2016-01-04T15:31:51.081Z",
       "iid" : 6,
       "labels" : [],
-      "user_notes_count": 1
+      "user_notes_count": 1,
+      "changes_count": "1"
    },
 ]
 ```
@@ -1077,6 +1096,7 @@ Example response:
     "sha": "8888888888888888888888888888888888888888",
     "merge_commit_sha": null,
     "user_notes_count": 7,
+    "changes_count": "1",
     "should_remove_source_branch": true,
     "force_remove_source_branch": false,
     "web_url": "http://example.com/example/example/merge_requests/1"
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 07331d05231..5a403f7593a 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -192,6 +192,12 @@ GET /projects
 ]
 ```
 
+You can filter by [custom attributes](custom_attributes.md) with:
+
+```
+GET /projects?custom_attributes[key]=value&custom_attributes[other_key]=other_value
+```
+
 ## List user projects
 
 Get a list of visible projects for the given user. When accessed without
diff --git a/doc/user/project/img/label_priority_sort_order.png b/doc/user/project/img/label_priority_sort_order.png
new file mode 100644
index 00000000000..21c7a76a322
--- /dev/null
+++ b/doc/user/project/img/label_priority_sort_order.png
diff --git a/doc/user/project/img/labels_filter_by_priority.png b/doc/user/project/img/labels_filter_by_priority.png
deleted file mode 100644
index 419e555e709..00000000000
--- a/doc/user/project/img/labels_filter_by_priority.png
+++ /dev/null
diff --git a/doc/user/project/img/priority_sort_order.png b/doc/user/project/img/priority_sort_order.png
new file mode 100644
index 00000000000..c558ec23b0e
--- /dev/null
+++ b/doc/user/project/img/priority_sort_order.png
diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md
index 21a2e1213ec..d7eb4bca89c 100644
--- a/doc/user/project/labels.md
+++ b/doc/user/project/labels.md
@@ -77,15 +77,32 @@ having their priority set to null.
 
 ![Prioritize labels](img/labels_prioritize.png)
 
-Now that you have labels prioritized, you can use the 'Priority' and 'Label
-priority' filters in the issues or merge requests tracker.
+Now that you have labels prioritized, you can use the 'Label priority' and 'Priority' 
+sort orders in the issues or merge requests tracker.
 
-The 'Label priority' filter puts issues with the highest priority label on top.
+In the following, everything applies to both issues and merge requests, but we'll
+refer to just issues for brevity.
 
-The 'Priority' filter sorts issues by their soonest milestone due date, then by
-label priority.
+The 'Label priority' sort order positions issues with higher priority labels
+toward the top, and issues with lower priority labels toward the bottom. A non-prioritized
+label is considered to have the lowest priority. For a given issue, we _only_ consider the
+highest priority label assigned to it in the comparison. ([We are discussing](https://gitlab.com/gitlab-org/gitlab-ce/issues/18554) 
+including all the labels in a given issue for this comparison.) Given two issues
+are equal according to this sort comparison, their relative order is equal, and 
+therefore it's not guaranteed that one will be always above the other.
+
+![Label priority sort order](img/label_priority_sort_order.png)
+
+The 'Priority' sort order comparison first considers an issue's milestone's due date,
+(if the issue is assigned a milestone and the milestone's due date exists), and then 
+secondarily considers the label priority comparison above. Sooner due dates results
+a higher sort order. If an issue doesn't have a milestone due date, it is equivalent to
+being assigned to a milestone that has a due date in the infinite future. Given two issues
+are equal according to this two-stage sort comparison, their relative order is equal, and 
+therefore it's not guaranteed that one will be always above the other.
+
+![Priority sort order](img/priority_sort_order.png)
 
-![Filter labels by priority](img/labels_filter_by_priority.png)
 
 ## Subscribe to labels