Skip to content

G
gitlab-ce
Commit 7017cba3 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'docs/uplift-award-emoji-api-doc' into 'master' 

Add more information and refactor format of award emoji-related topics

See merge request gitlab-org/gitlab-ce!24288
parents 28ca155b 8c326da2
Show whitespace changes
Inline Side-by-side
Showing with 126 additions and 103 deletions
doc/api/award_emoji.md
View file @ 7017cba3
# Award Emoji API # Award Emoji API
> [Introduced][ce-4575] in GitLab 8.9, Snippet support in 8.12 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575) in GitLab 8.9. Snippet support added in 8.12.
An [awarded emoji](../user/award_emojis.md) tells a thousand words.
An awarded emoji tells a thousand words, and can be awarded on issues, merge Emoji can be awarded on the following (known as "awardables"):
requests, snippets, and notes/comments. Issues, merge requests, snippets, and notes are further called
`awardables`. - [Issues](../user/project/issues/index.md) ([API](issues.md)).
- [Merge requests](../user/project/merge_requests/index.md) ([API](merge_requests.md)).
- [Snippets](../user/snippets.md) ([API](snippets.md)).
Emoji can also [be awarded](../user/award_emojis.html#award-emoji-for-comments) on comments (also known as notes). See also [Notes API](notes.md).
## Issues, merge requests, and snippets ## Issues, merge requests, and snippets
See [Award Emoji on Comments](#award-emoji-on-comments) for information on using these endpoints with comments.
### List an awardable's award emoji ### List an awardable's award emoji
Gets a list of all award emoji Get a list of all award emoji for a specified awardable.
``` ```text
GET /projects/:id/issues/:issue_iid/award_emoji GET /projects/:id/issues/:issue_iid/award_emoji
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji GET /projects/:id/merge_requests/:merge_request_iid/award_emoji
GET /projects/:id/snippets/:snippet_id/award_emoji GET /projects/:id/snippets/:snippet_id/award_emoji
...@@ -22,15 +29,17 @@ GET /projects/:id/snippets/:snippet_id/award_emoji ...@@ -22,15 +29,17 @@ GET /projects/:id/snippets/:snippet_id/award_emoji
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable | | `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
```bash Example request:
```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji
``` ```
Example Response: Example response:
```json ```json
[ [
...@@ -71,9 +80,9 @@ Example Response: ...@@ -71,9 +80,9 @@ Example Response:
### Get single award emoji ### Get single award emoji
Gets a single award emoji from an issue, snippet, or merge request. Get a single award emoji from an issue, snippet, or merge request.
``` ```text
GET /projects/:id/issues/:issue_iid/award_emoji/:award_id GET /projects/:id/issues/:issue_iid/award_emoji/:award_id
GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id GET /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
...@@ -82,16 +91,18 @@ GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id ...@@ -82,16 +91,18 @@ GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable | | `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
| `award_id` | integer | yes | The ID of the award emoji | | `award_id` | integer | yes | ID of the award emoji. |
Example request:
```bash ```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/1
``` ```
Example Response: Example response:
```json ```json
{ {
...@@ -114,9 +125,9 @@ Example Response: ...@@ -114,9 +125,9 @@ Example Response:
### Award a new emoji ### Award a new emoji
This end point creates an award emoji on the specified resource Create an award emoji on the specified awardable.
``` ```text
POST /projects/:id/issues/:issue_iid/award_emoji POST /projects/:id/issues/:issue_iid/award_emoji
POST /projects/:id/merge_requests/:merge_request_iid/award_emoji POST /projects/:id/merge_requests/:merge_request_iid/award_emoji
POST /projects/:id/snippets/:snippet_id/award_emoji POST /projects/:id/snippets/:snippet_id/award_emoji
...@@ -125,12 +136,12 @@ POST /projects/:id/snippets/:snippet_id/award_emoji ...@@ -125,12 +136,12 @@ POST /projects/:id/snippets/:snippet_id/award_emoji
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable | | `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
| `name` | string | yes | The name of the emoji, without colons | | `name` | string | yes | Name of the emoji without colons. |
```bash ```sh
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji?name=blowfish
``` ```
...@@ -157,10 +168,12 @@ Example Response: ...@@ -157,10 +168,12 @@ Example Response:
### Delete an award emoji ### Delete an award emoji
Sometimes its just not meant to be, and you'll have to remove your award. Only available to Sometimes it's just not meant to be and you'll have to remove the award.
admins or the author of the award.
``` NOTE: **Note:**
Only available to administrators or the author of the award.
```text
DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id DELETE /projects/:id/issues/:issue_iid/award_emoji/:award_id
DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id DELETE /projects/:id/merge_requests/:merge_request_iid/award_emoji/:award_id
DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
...@@ -169,42 +182,46 @@ DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id ...@@ -169,42 +182,46 @@ DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `issue_iid` | integer | yes | The internal ID of an issue | | `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
| `award_id` | integer | yes | The ID of an award_emoji | | `award_id` | integer | yes | ID of an award emoji. |
```bash ```sh
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/344
``` ```
## Award Emoji on Notes ## Award Emoji on Comments
The endpoints documented above are available for Notes as well. Notes Comments (also known as notes) are a sub-resource of issues, merge requests, and snippets.
are a sub-resource of Issues, Merge Requests, or Snippets. The examples below
describe working with Award Emoji on notes for an Issue, but can be
easily adapted for notes on a Merge Request.
### List a note's award emoji NOTE: **Note:**
The examples below describe working with award emoji on comments for an issue, but can be
easily adapted for comments on a merge request.
``` ### List a comment's award emoji
Get all award emoji for a comment (note).
```text
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
``` ```
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `issue_iid` | integer | yes | The internal ID of an issue | | `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | The ID of a note | | `note_id` | integer | yes | ID of a comment (note). |
Example request:
```bash ```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji
``` ```
Example Response: Example response:
```json ```json
[ [
...@@ -227,26 +244,30 @@ Example Response: ...@@ -227,26 +244,30 @@ Example Response:
] ]
``` ```
### Get single note's award emoji ### Get an award emoji for a comment
``` Get a single award emoji for a comment (note).
```text
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
``` ```
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `issue_iid` | integer | yes | The internal ID of an issue | | `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | The ID of a note | | `note_id` | integer | yes | ID of a comment (note). |
| `award_id` | integer | yes | The ID of the award emoji | | `award_id` | integer | yes | ID of the award emoji. |
Example request:
```bash ```sh
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2 curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji/2
``` ```
Example Response: Example response:
```json ```json
{ {
...@@ -267,26 +288,30 @@ Example Response: ...@@ -267,26 +288,30 @@ Example Response:
} }
``` ```
### Award a new emoji on a note ### Award a new emoji on a comment
``` Create an award emoji on the specified comment (note).
```text
POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
``` ```
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `issue_iid` | integer | yes | The internal ID of an issue | | `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | The ID of a note | | `note_id` | integer | yes | ID of a comment (note). |
| `name` | string | yes | The name of the emoji, without colons | | `name` | string | yes | Name of the emoji without colons. |
```bash Example request:
```sh
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji?name=rocket curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/notes/1/award_emoji?name=rocket
``` ```
Example Response: Example response:
```json ```json
{ {
...@@ -307,26 +332,28 @@ Example Response: ...@@ -307,26 +332,28 @@ Example Response:
} }
``` ```
### Delete an award emoji ### Delete an award emoji from a comment
Sometimes its just not meant to be, and you'll have to remove your award. Only available to Sometimes it's just not meant to be and you'll have to remove the award.
admins or the author of the award.
``` NOTE: **Note:**
Only available to administrators or the author of the award.
```text
DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id DELETE /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
``` ```
Parameters: Parameters:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- | |:------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
| `issue_iid` | integer | yes | The internal ID of an issue | | `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | The ID of a note | | `note_id` | integer | yes | ID of a comment (note). |
| `award_id` | integer | yes | The ID of an award_emoji | | `award_id` | integer | yes | ID of an award_emoji. |
Example request:
```bash ```sh
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/issues/80/award_emoji/345
``` ```
[ce-4575]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575
doc/user/award_emojis.md
View file @ 7017cba3
# Award emoji # Award emoji
> **Notes:** > - First [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825) in GitLab 8.2.
> - First [introduced][1825] in GitLab 8.2. > - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570) the usage of native emoji if the platform
> - GitLab 9.0 [introduced][ce-9570] the usage of native emojis if the platform
> supports them and falls back to images or CSS sprites. This change greatly > supports them and falls back to images or CSS sprites. This change greatly
> improved the award emoji performance overall. > improved award emoji performance overall.
When you're collaborating online, you get fewer opportunities for high-fives When you're collaborating online, you get fewer opportunities for high-fives
and thumbs-ups. Emoji can be awarded to issues, merge requests, snippets, and and thumbs-ups. Emoji can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md),
virtually everywhere where you can have a discussion. [snippets](snippets.md), and anywhere you can have a discussion.
![Award emoji](img/award_emoji_select.png) ![Award emoji](img/award_emoji_select.png)
Award emoji make it much easier to give and receive feedback without a long Award emoji make it much easier to give and receive feedback without a long
comment thread. Comments that are only emoji will automatically become comment thread.
award emoji.
For information on the relevant API, see [Award Emoji API](../api/award_emoji.md).
## Sort issues and merge requests on vote count ## Sort issues and merge requests on vote count
> [Introduced][2871] in GitLab 8.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781) in GitLab 8.5.
You can quickly sort issues and merge requests by the number of votes they You can quickly sort issues and merge requests by the number of votes they
have received. The sort options can be found in the dropdown menu as "Most have received. The sort options can be found in the dropdown menu as "Most
...@@ -32,20 +32,16 @@ downvotes. ...@@ -32,20 +32,16 @@ downvotes.
## Award emoji for comments ## Award emoji for comments
> [Introduced][4291] in GitLab 8.9. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291) in GitLab 8.9.
Award emoji can also be applied to individual comments when you want to Award emoji can also be applied to individual comments when you want to
celebrate an accomplishment or agree with an opinion. celebrate an accomplishment or agree with an opinion.
To add an award emoji, click the smile in the top right of the comment and pick To:
an emoji from the dropdown. If you want to remove an award emoji, just click
the emoji again and the vote will be removed. - Add an award emoji, click the smile in the top right of the comment and pick an emoji from the dropdown.
- Remove an award emoji, click the emoji again and the vote will be removed.
![Picking an emoji for a comment](img/award_emoji_comment_picker.png) ![Picking an emoji for a comment](img/award_emoji_comment_picker.png)
![An award emoji has been applied to a comment](img/award_emoji_comment_awarded.png) ![An award emoji has been applied to a comment](img/award_emoji_comment_awarded.png)
[2871]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2781
[1825]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825
[4291]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4291
[ce-9570]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7