From 3ab729d58efcf4c55971c0ca876ce9e12372a969 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Tue, 11 Jun 2019 17:59:19 +0000 Subject: Docs: Updating issue data and actions doc --- .../project/issues/img/comment-or-discussion.png | Bin 0 -> 8378 bytes .../project/issues/img/create_mr_from_issue.png | Bin 0 -> 21286 bytes .../issues/img/issues_main_view_numbered.jpg | Bin 205803 -> 0 bytes .../issues/img/issues_main_view_numbered.png | Bin 0 -> 278285 bytes doc/user/project/issues/img/reopen-issue.png | Bin 0 -> 2522 bytes doc/user/project/issues/img/report-abuse.png | Bin 0 -> 1620 bytes doc/user/project/issues/img/show-all-activity.png | Bin 0 -> 8119 bytes doc/user/project/issues/index.md | 2 +- doc/user/project/issues/issue_data_and_actions.md | 260 +++++++++++++-------- 9 files changed, 161 insertions(+), 101 deletions(-) create mode 100644 doc/user/project/issues/img/comment-or-discussion.png create mode 100644 doc/user/project/issues/img/create_mr_from_issue.png delete mode 100644 doc/user/project/issues/img/issues_main_view_numbered.jpg create mode 100644 doc/user/project/issues/img/issues_main_view_numbered.png create mode 100644 doc/user/project/issues/img/reopen-issue.png create mode 100644 doc/user/project/issues/img/report-abuse.png create mode 100644 doc/user/project/issues/img/show-all-activity.png (limited to 'doc') diff --git a/doc/user/project/issues/img/comment-or-discussion.png b/doc/user/project/issues/img/comment-or-discussion.png new file mode 100644 index 00000000000..ccecc9fa39f Binary files /dev/null and b/doc/user/project/issues/img/comment-or-discussion.png differ diff --git a/doc/user/project/issues/img/create_mr_from_issue.png b/doc/user/project/issues/img/create_mr_from_issue.png new file mode 100644 index 00000000000..680c42b5df0 Binary files /dev/null and b/doc/user/project/issues/img/create_mr_from_issue.png differ diff --git a/doc/user/project/issues/img/issues_main_view_numbered.jpg b/doc/user/project/issues/img/issues_main_view_numbered.jpg deleted file mode 100644 index b4b68476d24..00000000000 Binary files a/doc/user/project/issues/img/issues_main_view_numbered.jpg and /dev/null differ diff --git a/doc/user/project/issues/img/issues_main_view_numbered.png b/doc/user/project/issues/img/issues_main_view_numbered.png new file mode 100644 index 00000000000..16cb6b497b0 Binary files /dev/null and b/doc/user/project/issues/img/issues_main_view_numbered.png differ diff --git a/doc/user/project/issues/img/reopen-issue.png b/doc/user/project/issues/img/reopen-issue.png new file mode 100644 index 00000000000..1749be31239 Binary files /dev/null and b/doc/user/project/issues/img/reopen-issue.png differ diff --git a/doc/user/project/issues/img/report-abuse.png b/doc/user/project/issues/img/report-abuse.png new file mode 100644 index 00000000000..f189cbf1d36 Binary files /dev/null and b/doc/user/project/issues/img/report-abuse.png differ diff --git a/doc/user/project/issues/img/show-all-activity.png b/doc/user/project/issues/img/show-all-activity.png new file mode 100644 index 00000000000..c43ba75ce25 Binary files /dev/null and b/doc/user/project/issues/img/show-all-activity.png differ diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 94865ad46ee..8d9e2e9db48 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -123,7 +123,7 @@ For more information, see [Crosslinking issues](crosslinking_issues.md). - [Close an issue](closing_issues.md) - [Move an issue](moving_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 diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index fc11c0251e0..da585022263 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -4,11 +4,13 @@ Please read through the [GitLab Issue Documentation](index.md) for an overview o ## 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 @@ -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 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. -Comments and system notes also appear automatically in response to various actions and content updates. +Many of the elements of the issue screen refresh automatically, such as the title and +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 -- Close issue: close this issue -- Edit: edit the same fields available when you create an issue. +Clicking on **New issue** will open a new window to create a new issue in the same project. +Clicking on **Close issue** will close this issue, but it will not be deleted. If the +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 -- Add todo: add that issue to your [GitLab Todo](../../../workflow/todos.md) list -- Mark todo as done: mark that issue as done (reflects on the Todo list) +You can click **add todo** to add the issue to your [GitLab Todo](../../../workflow/todos.md) +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 -Whenever someone starts to work on an issue, it can be assigned -to that person. The assignee can be changed as much as needed. -The idea is that the assignee is responsible for that issue until -it's reassigned to someone else to take it from there. +An issue can be assigned to yourself, another person, or [many people](#31-multiple-assignees-STARTER). +The assignee(s) can be changed as much as needed. The idea is that the assignees are +responsible for that issue until it's reassigned to someone else to take it from there. +When assigned to someone, it will appear in their assigned issues list. -> **Tip:** -if a user is not member of that project, it can only be +TIP: **Tip:** +If a user is not member of that project, it can only be assigned to them if they created the issue themselves. ##### 3.1. Multiple Assignees **[STARTER]** -Often multiple people work on the same issue together, -which can be especially difficult to track in large teams -where there is shared ownership of an issue. +Often multiple people work on the same issue together, which can be especially difficult +to track in large teams where there is shared ownership of an issue. 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. -- Spend: add the time spent on the resolution of the issue +#### 7. Due date -> **Note:** -Both estimate and spend times are set via [GitLab Quick Actions](../quick_actions.md). +When you work on a tight schedule, it's important to have a way to set a deadline for +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 -have a way to set a deadline for 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. +Group Labels, which allow you to use the same labels for all projects within the same +group, can be also given to issues. They work exactly the same, but they are immediately +available to all projects in the group. -#### 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 -organize workflows, and they enable you to work with the -[GitLab Issue Board](index.md#issue-boards). +#### 9. Weight **[STARTER]** -Group Labels, which allow you to use the same labels for a -group of projects, can be also given to issues. They work exactly the same, -but they are immediately available to all projects in the group. +[Assign a weight](../../../workflow/issue_weight.md) to an issue. +Larger values are used to indicate more effort is required to complete the issue. Only +positive values or zero are allowed. -> **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**. +#### 10. Confidentiality -#### 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 - want to receive notifications on each new input, subscribe to it. -- Unsubscribe: if you are receiving notifications on that issue but no +Click on the icon to enable/disable [notifications](../../../workflow/notifications.md#issue--epics--merge-request-events) +for the issue. This will automatically enable if you participate in the issue in any way. + +- **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. -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` - is the `project-name`, and `xxx` is the issue number. +#### 20. Award emoji -#### 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. -- Description: a large text field which fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), - to describe all the details of the issue. +TIP: **Tip:** +Posting "+1" as a comment in a thread spams all subscribed participants of that 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 - `@username` or `@groupname` and they will be notified via todos and email, unless - they have disabled all notifications in their profile settings. -- 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. +You can filter what is displayed in the issue history by clicking on **Show all activity** +and selecting either **Show comments only**, which only shows discussions and hides +updates to the issue, or **Show history only**, which hides discussions and only shows updates. -To change your [notification settings](../../../workflow/notifications.md), navigate to -**Profile Settings** > **Notifications** > **Global notification level** -and choose your preference from the dropdown menu. +![Show all activity](img/show-all-activity.png) -> **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. +#### 22. Create Merge Request -#### 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 - or in the issue discussion thread. +![Create MR from issue](img/create_mr_from_issue.png) -#### 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:** -Posting "+1" as a comment in a thread spams all subscribed -participants of that issue. Awarding an emoji is a way to let them -know you like it without spamming them. +All comments and updates to the issue are tracked and listed here, but this can be +filtered, as shown above. -#### 16. Thread +#### 24. Comments -- Comments: collaborate to that issue by posting comments in its thread. - These text fields also fully support - [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). +Collaborate in the issue by posting comments in its thread. This text field also fully +supports [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 "Start discussion": start a thread within that issue's thread to discuss specific points. -- Click "Comment and close issue": post your comment and close that issue in one click. +- Click **Comment** and your comment will be published. +- Choose **Start discussion** from the dropdown list and start a new [discussion thread](../../discussions/index.md#threaded-discussions) + 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. - 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. +You can also close the issue from here, so you don't need to scroll to the top of the issue page. -- cgit v1.2.3