diff options
author | Shinya Maeda <shinya@gitlab.com> | 2017-11-07 15:23:54 +0300 |
---|---|---|
committer | Shinya Maeda <shinya@gitlab.com> | 2017-11-07 15:23:54 +0300 |
commit | bbdb0cf05141cdf9931e2aa673bf7a2ce5db0078 (patch) | |
tree | cf0e3da342c5543d817484d5130bc1e69012359a /doc | |
parent | ce7b05f41d3941552320c23dc06f9f2b076099ed (diff) | |
parent | 666ab4882f2c6d385c04afe269ddf5b11f795b19 (diff) |
Merge branch 'master' into 38464-k8s-apps
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/custom_attributes.md | 27 | ||||
-rw-r--r-- | doc/api/groups.md | 6 | ||||
-rw-r--r-- | doc/api/merge_requests.md | 22 | ||||
-rw-r--r-- | doc/api/projects.md | 6 | ||||
-rw-r--r-- | doc/user/project/img/label_priority_sort_order.png | bin | 0 -> 101667 bytes | |||
-rw-r--r-- | doc/user/project/img/labels_filter_by_priority.png | bin | 38717 -> 0 bytes | |||
-rw-r--r-- | doc/user/project/img/priority_sort_order.png | bin | 0 -> 102242 bytes | |||
-rw-r--r-- | doc/user/project/labels.md | 29 |
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 Binary files differnew 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 Binary files differdeleted 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 Binary files differnew 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 |