Commit 1a98abfc authored by Marcia Ramos's avatar Marcia Ramos

Merge branch 'docs-issue-data' into 'master'

Docs: Updating issue data and actions doc

See merge request gitlab-org/gitlab-ce!28810
parents 920fa740 3ab729d5
...@@ -123,7 +123,7 @@ For more information, see [Crosslinking issues](crosslinking_issues.md). ...@@ -123,7 +123,7 @@ For more information, see [Crosslinking issues](crosslinking_issues.md).
- [Close an issue](closing_issues.md) - [Close an issue](closing_issues.md)
- [Move an issue](moving_issues.md) - [Move an issue](moving_issues.md)
- [Delete an issue](deleting_issues.md) - [Delete an issue](deleting_issues.md)
- [Create a merge request from an issue](issue_data_and_actions.md#18-new-merge-request) - [Create a merge request from an issue](issue_data_and_actions.md#22-create-merge-request)
## Advanced issue management ## Advanced issue management
......
...@@ -4,11 +4,13 @@ Please read through the [GitLab Issue Documentation](index.md) for an overview o ...@@ -4,11 +4,13 @@ Please read through the [GitLab Issue Documentation](index.md) for an overview o
## Parts of an Issue ## Parts of an Issue
The image below illustrates what an issue looks like: The image below illustrates what an issue may look like. Note that certain parts will
look slightly different or will be absent, depending on the version of GitLab being used
and the permissions of the user viewing the issue.
![Issue view](img/issues_main_view_numbered.jpg) ![Issue view](img/issues_main_view_numbered.png)
You can find all the information on that issue on one screen. You can find all the information for that issue on one screen.
### Issue screen ### Issue screen
...@@ -16,157 +18,215 @@ An issue starts with its status (open or closed), followed by its author, ...@@ -16,157 +18,215 @@ An issue starts with its status (open or closed), followed by its author,
and includes many other functionalities, numbered in the image above to and includes many other functionalities, numbered in the image above to
explain what they mean, one by one. explain what they mean, one by one.
Many of the elements of the issue screen refresh automatically, such as the title and description, when they are changed by another user. Many of the elements of the issue screen refresh automatically, such as the title and
Comments and system notes also appear automatically in response to various actions and content updates. description, when they are changed by another user. Comments and system notes also
update automatically in response to various actions and content updates.
#### 1. New Issue, close issue, edit #### 1. New Issue, close issue (reopen issue, report issue)
- New issue: create a new issue in the same project Clicking on **New issue** will open a new window to create a new issue in the same project.
- Close issue: close this issue Clicking on **Close issue** will close this issue, but it will not be deleted. If the
- Edit: edit the same fields available when you create an issue. issue is already closed, you can still access it and the button will show **Reopen issue**, as shown below,
which you can click to reopen the issue. A reopened issue is no different from any
other issue.
![Reopen Issue](img/reopen-issue.png)
If you do not have rights to modify the issue, the **close issue** button will be
replaced with **report issue**, which you can click to [submit an abuse report](../../abuse_reports.md)
about the issue. It will also appear if you have rights to modify the issue, but only
after it is closed.
![Report Abuse](img/report-abuse.png)
#### 2. Todos #### 2. Todos
- Add todo: add that issue to your [GitLab Todo](../../../workflow/todos.md) list You can click **add todo** to add the issue to your [GitLab Todo](../../../workflow/todos.md)
- Mark todo as done: mark that issue as done (reflects on the Todo list) list. If it is already on your todo list, the buttom will show **mark todo as done**,
which you can click to mark that issue as done (which will be reflected in the Todo list).
#### 3. Assignee #### 3. Assignee
Whenever someone starts to work on an issue, it can be assigned An issue can be assigned to yourself, another person, or [many people](#31-multiple-assignees-STARTER).
to that person. The assignee can be changed as much as needed. The assignee(s) can be changed as much as needed. The idea is that the assignees are
The idea is that the assignee is responsible for that issue until responsible for that issue until it's reassigned to someone else to take it from there.
it's reassigned to someone else to take it from there. When assigned to someone, it will appear in their assigned issues list.
> **Tip:** TIP: **Tip:**
if a user is not member of that project, it can only be If a user is not member of that project, it can only be
assigned to them if they created the issue themselves. assigned to them if they created the issue themselves.
##### 3.1. Multiple Assignees **[STARTER]** ##### 3.1. Multiple Assignees **[STARTER]**
Often multiple people work on the same issue together, Often multiple people work on the same issue together, which can be especially difficult
which can be especially difficult to track in large teams to track in large teams where there is shared ownership of an issue.
where there is shared ownership of an issue.
In [GitLab Starter](https://about.gitlab.com/pricing/), you can In [GitLab Starter](https://about.gitlab.com/pricing/), you can
assign multiple people to an issue. [assign multiple people](multiple_assignees_for_issues.md) to an issue.
#### 4. Epic **[ULTIMATE]**
You can assign issues to an [Epic](../../group/epics/index.md), which allows better
management of groups of related issues.
Learn more in the [Multiple Assignees documentation](multiple_assignees_for_issues.md). #### 5. Milestone
#### 4. Milestone Select a [milestone](../milestones/index.md) to attribute that issue to.
- Select a [milestone](../milestones/index.md) to attribute that issue to. #### 6. Time Tracking
#### 5. Time Tracking Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../../../workflow/time_tracking.md).
You can add an [estimate of the time it will take](../../../workflow/time_tracking.md#estimates)
to resolve the issue, and also add [the time spent](../../../workflow/time_tracking.md#time-spent)
on the resolution of the issue.
- Estimate time: add an estimate of the time it will take to resolve the issue. #### 7. Due date
- Spend: add the time spent on the resolution of the issue
> **Note:** When you work on a tight schedule, it's important to have a way to set a deadline for
Both estimate and spend times are set via [GitLab Quick Actions](../quick_actions.md). implementations and for solving problems. This can be done in the [due date](due_dates.md)
element. Due dates can be changed as many times as needed.
Learn more in the [Time Tracking documentation](../../../workflow/time_tracking.md). #### 8. Labels
#### 6. Due date Categorize issues by giving them [labels](../labels.md). They help to organize workflows,
and they enable you to work with the [GitLab Issue Board](index.md#issue-boards).
When you work on a tight schedule, it's important to Group Labels, which allow you to use the same labels for all projects within the same
have a way to set a deadline for implementations and for solving group, can be also given to issues. They work exactly the same, but they are immediately
problems. This can be done in the [due date](due_dates.md) element. Due dates available to all projects in the group.
can be changed as many times as needed.
#### 7. Labels TIP: **Tip:**
If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown menu
from which you can select **Create new label**.
Categorize issues by giving them [labels](../labels.md). They help to #### 9. Weight **[STARTER]**
organize workflows, and they enable you to work with the
[GitLab Issue Board](index.md#issue-boards).
Group Labels, which allow you to use the same labels for a [Assign a weight](../../../workflow/issue_weight.md) to an issue.
group of projects, can be also given to issues. They work exactly the same, Larger values are used to indicate more effort is required to complete the issue. Only
but they are immediately available to all projects in the group. positive values or zero are allowed.
> **Tip:** #### 10. Confidentiality
If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown menu from which you can select **Create new label**.
#### 8. Weight **[STARTER]** You can [set an issue to be confidential](confidential_issues.md). When set, unauthorized
users will not be able to access the issue, and will not see it listed in project
issue boards or the issue list.
- Assign a weight. Larger values are used to indicate more effort is required to complete the issue. Only positive values or zero are allowed. #### 11. Lock issue
Learn more in the [Issue Weight documentation](../../../workflow/issue_weight.md). You can [lock the discussions](../../discussions/index.md#lock-discussions) in the issue,
to prevent further comments from being added.
#### 9. Participants #### 12. Participants
- People involved in that issue (mentioned in the description or in the [discussion](../../discussions/index.md)). All the users involved in that issue. Either they participated in the [discussion](../../discussions/index.md),
or were mentioned in the description or discussions.
#### 10. Notifications #### 13. Notifications
- Subscribe: if you are not a participant of the discussion on that issue, but Click on the icon to enable/disable [notifications](../../../workflow/notifications.md#issue--epics--merge-request-events)
want to receive notifications on each new input, subscribe to it. for the issue. This will automatically enable if you participate in the issue in any way.
- Unsubscribe: if you are receiving notifications on that issue but no
- **Enable**: If you are not a participant in the discussion on that issue, but
want to receive notifications on each update, subscribe to it.
- **Disable**: If you are receiving notifications for updates to that issue but no
longer want to receive them, unsubscribe from it. longer want to receive them, unsubscribe from it.
Read more in the [notifications documentation](../../../workflow/notifications.md#issue--epics--merge-request-events). #### 14. Reference
- A quick "copy to clipboard" button for that issue's reference, which looks like `foo/bar#xxx`,
where `foo` is the `username` or `groupname`, `bar` is the `project-name`, and
`xxx` is the issue number.
#### 15. Edit
Clicking this icon opens the issue for editing, and you will have access to all the
same fields as when the issue was created. This icon will not display if the user
does not have permission to edit the issue.
#### 16. Description
The plain text title and description of the issue fill the top center of the issue page.
The description fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm),
allowing many formatting options.
#### 17. Mentions
You can mention a user or a group present in your GitLab instance with `@username` or
`@groupname` and they will be notified via todos and email, unless they have disabled
all notifications in their profile settings. This is controlled in the
[notification settings](../../../workflow/notifications.md).
Mentions for yourself (the current logged in user), will be highlighted in a different
color, allowing you to easily see which comments involve you, helping you focus on
them quickly.
TIP: **Tip:**
Avoid mentioning `@all` in issues and merge requests, as it sends an email notification
to all the members of that project's group, which can be interpreted as spam.
#### 18. Related Issues **[STARTER]**
Issues that were mentioned as [related issues](related_issues.md) are listed here.
You can also click the `+` to add more related issues.
#### 19. Related Merge Requests
#### 11. Reference Merge requests that were mentioned in that issue's description or in the issue discussion
thread are listed as [related merge requests](crosslinking_issues.md#from-merge-requests) here.
Also, if the current issue was mentioned as related in another merge request, that
merge request will be listed here.
- A quick "copy to clipboard" button for that issue's reference, `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` #### 20. Award emoji
is the `project-name`, and `xxx` is the issue number.
#### 12. Title and description You can award an emoji to that issue. There are shortcuts to "thumbs_up" and "thumbs_down",
or you can click on the light gray "face" to choose a different reaction from the
dropdown list of available [GitLab Flavored Markdown Emoji](../../markdown.md#emoji).
- Title: a plain text title for describing the subject of the issue. TIP: **Tip:**
- Description: a large text field which fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), Posting "+1" as a comment in a thread spams all subscribed participants of that issue,
to describe all the details of the issue. clutters the discussion threads, and is not recommended. Awarding an emoji is a way
to let them know your reaction without spamming them.
#### 13. Mentions #### 21. Show all activity
- You can mention a user or a group present in your GitLab instance with You can filter what is displayed in the issue history by clicking on **Show all activity**
`@username` or `@groupname` and they will be notified via todos and email, unless and selecting either **Show comments only**, which only shows discussions and hides
they have disabled all notifications in their profile settings. updates to the issue, or **Show history only**, which hides discussions and only shows updates.
- Mentions for yourself (the current logged in user), will be highlighted
in a different color, allowing you to easily see which comments involve you,
helping you focus on them quickly.
To change your [notification settings](../../../workflow/notifications.md), navigate to ![Show all activity](img/show-all-activity.png)
**Profile Settings** > **Notifications** > **Global notification level**
and choose your preference from the dropdown menu.
> **Tip:** #### 22. Create Merge Request
Avoid mentioning `@all` in issues and merge requests,
as it sends an email notification
to all the members of that project's group, which can be
interpreted as spam.
#### 14. Related Merge Requests Create a new branch and [WIP merge request](../merge_requests/work_in_progress_merge_requests.md)
in one action. The branch will be named `issuenumber-title` by default, but you can
choose any name, and GitLab will verify that it is not already in use. The merge request
will automatically inherit the milestone and labels of the issue, and will be set to
close the issue when it is merged.
- Any merge requests mentioned in that issue's description ![Create MR from issue](img/create_mr_from_issue.png)
or in the issue discussion thread.
#### 15. Award emoji Optionally, you can choose to create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue)
only, named after that issue.
- Award an emoji to that issue. #### 23. Issue history
> **Tip:** All comments and updates to the issue are tracked and listed here, but this can be
Posting "+1" as a comment in a thread spams all subscribed filtered, as shown above.
participants of that issue. Awarding an emoji is a way to let them
know you like it without spamming them.
#### 16. Thread #### 24. Comments
- Comments: collaborate to that issue by posting comments in its thread. Collaborate in the issue by posting comments in its thread. This text field also fully
These text fields also fully support supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
#### 17. Comment, start a discussion, or comment and close #### 25. Submit Comment, start a discussion, or comment and close
Once you write a comment, you can either: Once you write a comment, you can:
- Click "Comment" and your comment will be published. - Click **Comment** and your comment will be published.
- Click "Start discussion": start a thread within that issue's thread to discuss specific points. - Choose **Start discussion** from the dropdown list and start a new [discussion thread](../../discussions/index.md#threaded-discussions)
- Click "Comment and close issue": post your comment and close that issue in one click. within that issue's main thread to discuss specific points. This invites other participants
to reply directly to your discussion, keeping related comments grouped together.
#### 18. New Merge Request ![Comment or discussion](img/comment-or-discussion.png)
- Create a new merge request (with a new source branch named after the issue) in one action. You can also close the issue from here, so you don't need to scroll to the top of the issue page.
The merge request will automatically inherit the milestone and labels of the issue. The merge
request will automatically close that issue when it is merged.
- Optionally, you can just create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue)
named after that issue.
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