Skip to content

G
gitlab-ce
Commit e635592d authored by Evan Read's avatar Evan Read
Browse files
Options

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

parent 4a6c7661
Hide whitespace changes
Inline Side-by-side
Showing with 128 additions and 102 deletions
doc/api/award_emoji.md
View file @ e635592d
# 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
requests, snippets, and notes/comments. Issues, merge requests, snippets, and notes are further called
`awardables`.
Emojis can be awarded on the following (known as "awardables"):
- [Issues](../user/project/issues/index.md)
- [Merge requests](../user/project/merge_requests/index.md)
- [Snippets](../user/snippets.md)
- Notes
Emojis can also [be awarded](../user/award_emojis.html#award-emoji-for-comments) on comments.
## Issues, merge requests, and snippets
See [Award Emoji on Notes](#award-emoji-on-notes) for information on using these endpoints with notes.
### 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/merge_requests/:merge_request_iid/award_emoji
GET /projects/:id/snippets/:snippet_id/award_emoji
......@@ -21,16 +29,18 @@ GET /projects/:id/snippets/:snippet_id/award_emoji
Parameters:
| 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 |
| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `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
```
Example Response:
Example response:
```json
[
......@@ -71,9 +81,9 @@ Example Response:
### 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/merge_requests/:merge_request_iid/award_emoji/:award_id
GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
......@@ -81,17 +91,19 @@ GET /projects/:id/snippets/:snippet_id/award_emoji/:award_id
Parameters:
| 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 |
| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
| `award_id` | integer | yes | The ID of the award emoji |
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
| `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
```
Example Response:
Example response:
```json
{
......@@ -114,9 +126,9 @@ Example Response:
### 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/merge_requests/:merge_request_iid/award_emoji
POST /projects/:id/snippets/:snippet_id/award_emoji
......@@ -124,13 +136,13 @@ POST /projects/:id/snippets/:snippet_id/award_emoji
Parameters:
| 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 |
| `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable |
| `name` | string | yes | The name of the emoji, without colons |
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
| `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
```
......@@ -157,10 +169,12 @@ Example Response:
### Delete an award emoji
Sometimes its just not meant to be, and you'll have to remove your award. Only available to
admins or the author of the award.
Sometimes it's just not meant to be and you'll have to remove 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/merge_requests/:merge_request_iid/award_emoji/:award_id
DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
......@@ -168,43 +182,48 @@ DELETE /projects/:id/snippets/:snippet_id/award_emoji/:award_id
Parameters:
| 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 |
| `issue_iid` | integer | yes | The internal ID of an issue |
| `award_id` | integer | yes | The ID of an award_emoji |
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. |
| `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
```
## Award Emoji on Notes
The endpoints documented above are available for Notes as well. Notes
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.
Notes are a sub-resource of issues, merge requests, and snippets. The endpoints documented above
are available for notes as well.
### List a note's award emoji
NOTE: **Note:**
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 emojis
Get all award emojis for a note.
```text
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
```
Parameters:
| 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 |
| `issue_iid` | integer | yes | The internal ID of an issue |
| `note_id` | integer | yes | The ID of a note |
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | ID of a 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
```
Example Response:
Example response:
```json
[
......@@ -227,26 +246,30 @@ Example Response:
]
```
### Get single note's award emoji
### Get an award emoji for a note
```
Get a single award emoji for a note.
```text
GET /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji/:award_id
```
Parameters:
| 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 |
| `issue_iid` | integer | yes | The internal ID of an issue |
| `note_id` | integer | yes | The ID of a note |
| `award_id` | integer | yes | The ID of the award emoji |
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | ID of a note. |
| `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
```
Example Response:
Example response:
```json
{
......@@ -269,24 +292,28 @@ Example Response:
### Award a new emoji on a note
```
Create an award emoji on the specified note.
```text
POST /projects/:id/issues/:issue_iid/notes/:note_id/award_emoji
```
Parameters:
| 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 |
| `issue_iid` | integer | yes | The internal ID of an issue |
| `note_id` | integer | yes | The ID of a note |
| `name` | string | yes | The name of the emoji, without colons |
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | ID of a note. |
| `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
```
Example Response:
Example response:
```json
{
......@@ -307,26 +334,28 @@ Example Response:
}
```
### Delete an award emoji
### Delete an award emoji from a note
Sometimes its just not meant to be, and you'll have to remove your award. Only available to
admins or the author of the award.
Sometimes it's just not meant to be and you'll have to remove 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
```
Parameters:
| 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 |
| `issue_iid` | integer | yes | The internal ID of an issue |
| `note_id` | integer | yes | The ID of a note |
| `award_id` | integer | yes | The ID of an award_emoji |
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `issue_iid` | integer | yes | Internal ID of an issue. |
| `note_id` | integer | yes | ID of a note. |
| `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
```
[ce-4575]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4575
doc/user/award_emojis.md
View file @ e635592d
# Award emoji
> **Notes:**
> - First [introduced][1825] in GitLab 8.2.
> - GitLab 9.0 [introduced][ce-9570] the usage of native emojis if the platform
> - First [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1825) in GitLab 8.2.
> - GitLab 9.0 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9570) the usage of native emojis if the platform
> 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
and thumbs-ups. Emoji can be awarded to issues, merge requests, snippets, and
virtually everywhere where you can have a discussion.
and thumbs-ups. Emojis can be awarded to [issues](project/issues/index.md), [merge requests](project/merge_requests/index.md),
[snippets](snippets.md), and virtually everywhere where you can have a discussion.
![Award emoji](img/award_emoji_select.png)
Award emoji make it much easier to give and receive feedback without a long
comment thread. Comments that are only emoji will automatically become
award emoji.
Award emojis make it much easier to give and receive feedback without a long
comment thread. Comments that are only emojis will automatically become
award emojis.
For information on the relevant API, see [Award Emoji API](../api/award_emoji.md).
## 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
have received. The sort options can be found in the dropdown menu as "Most
......@@ -32,20 +33,16 @@ downvotes.
## 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
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
an emoji from the dropdown. If you want to remove an award emoji, just click
the emoji again and the vote will be removed.
To:
- 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)
![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