Commit 6386e42f authored by Sean Packham's avatar Sean Packham

Merge branch 'docs/new-topic-issues' into 'master'

New doc topic: issues

Closes #27650

See merge request !11075
parents 59c9ec5c b13b22d0
......@@ -60,11 +60,8 @@ Manage files and branches from the UI (user interface):
### Issues and Merge Requests (MRs)
- [Discussions](user/discussions/index.md) Threads, comments, and resolvable discussions in issues, commits, and merge requests.
- Issues
- [Create an issue](gitlab-basics/create-issue.md#how-to-create-an-issue-in-gitlab)
- [Confidential Issues](user/project/issues/confidential_issues.md)
- [Automatic issue closing](user/project/issues/automatic_issue_closing.md)
- [Issue Boards](user/project/issue_board.md)
- [Issues](user/project/issues/index.md)
- [Issue Board](user/project/issue_board.md)
- [Issues and merge requests templates](user/project/description_templates.md): Create templates for submitting new issues and merge requests.
- [Labels](user/project/labels.md): Categorize your issues or merge requests based on descriptive titles.
- [Merge Requests](user/project/merge_requests/index.md)
......
......@@ -11,5 +11,5 @@ Step-by-step guides on the basics of working with Git and GitLab.
- [Fork a project](fork-project.md)
- [Add a file](add-file.md)
- [Add an image](add-image.md)
- [Create an issue](create-issue.md)
- [Create an issue](../user/project/issues/create_new_issue.md)
- [Create a merge request](add-merge-request.md)
# How to create an Issue in GitLab
The issue tracker is a good place to add things that need to be improved or
solved in a project.
---
1. Go to the project where you'd like to create the issue and navigate to the
**Issues** tab on top.
![Issues](img/project_navbar.png)
1. Click on the **New issue** button on the right side of your screen.
![New issue](img/new_issue_button.png)
1. At the very minimum, add a title and a description to your issue.
You may assign it to a user, add a milestone or add labels (all optional).
![Issue title and description](img/new_issue_page.png)
1. When ready, click on **Submit issue**.
---
Your Issue will now be added to the issue tracker of the project you opened it
at and will be ready to be reviewed. You can comment on it and mention the
people involved. You can also link issues to the merge requests where the issues
are solved. To do this, you can use an
[issue closing pattern](../user/project/issues/automatic_issue_closing.md).
This document was moved to [another location](../user/project/issues/index.md#new-issue).
......@@ -11,7 +11,7 @@ Create projects and groups.
Create issues, labels, milestones, cast your vote, and review issues.
- [Create a new issue](../gitlab-basics/create-issue.md)
- [Create a new issue](../user/project/issues/index.md#new-issue)
- [Assign labels to issues](../user/project/labels.md)
- [Use milestones as an overview of your project's tracker](../user/project/milestones/index.md)
- [Use voting to express your like/dislike to issues and merge requests](../workflow/award_emoji.md)
......
# Closing Issues
Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
## Directly
Whenever you decide that's no longer need for that issue,
close the issue using the close button:
![close issue - button](img/button_close_issue.png)
## Via Merge Request
When a merge request resolves the discussion over an issue, you can
make it close that issue(s) when merged.
All you need is to use a [keyword](automatic_issue_closing.md)
accompanying the issue number, add to the description of that MR.
In this example, the keyword "closes" prefixing the issue number will create a relationship
in such a way that the merge request will close the issue when merged.
Mentioning various issues in the same line also works for this purpose:
```md
Closes #333, #444, #555 and #666
```
If the issue is in a different repository rather then the MR's,
add the full URL for that issue(s):
```md
Closes #333, #444, and https://gitlab.com/<username>/<projectname>/issues/<xxx>
```
All the following keywords will produce the same behaviour:
- Close, Closes, Closed, Closing, close, closes, closed, closing
- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
![merge request closing issue when merged](img/merge_request_closes_issue.png)
If you use any other word before the issue number, the issue and the MR will
link to each other, but the MR will NOT close the issue(s) when merged.
![mention issues in MRs - closing and related](img/closing_and_related_issues.png)
## From the Issue Board
You can close an issue from [Issue Boards](../issue_board.md) by draging an issue card
from its list and dropping into **Closed**.
![close issue from the Issue Board](img/close_issue_from_board.gif)
## Customizing the issue closing patern
Alternatively, a GitLab **administrator** can
[customize the issue closing patern](../../../administration/issue_closing_pattern.md).
# Create a new Issue
Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
When you create a new issue, you'll be prompted to fill in
the information illustrated on the image below.
![New issue from the issues list](img/new_issue.png)
Read through the [issues functionalities documentation](issues_functionalities.md#issues-functionalities)
to understand these fields one by one.
## New issue from the Issue Tracker
Navigate to your **Project's Dashboard** > **Issues** > **New Issue** to create a new issue:
![New issue from the issue list view](img/new_issue_from_tracker_list.png)
## New issue from an opened issue
From an **opened issue** in your project, click **New Issue** to create a new
issue in the same project:
![New issue from an open issue](img/new_issue_from_open_issue.png)
## New issue from the project's dashboard
From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown
menu with a few options. Select **New Issue** to create an issue in that project:
![New issue from a project's dashboard](img/new_issue_from_projects_dashboard.png)
## New issue from the Issue Board
From an Issue Board, create a new issue by clicking on the plus sign (**+**) on the top of a list.
It opens a new issue for that project labeled after its respective list.
![From the issue board](img/new_issue_from_issue_board.png)
# Crosslinking Issues
Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
## From Commit Messages
Every time you mention an issue in your commit message, you're creating
a relationship between the two stages of the development workflow: the
issue itself and the first commit related to that issue.
If the issue and the code you're committing are both in the same project,
you simply add `#xxx` to the commit message, where `xxx` is the issue number.
If they are not in the same project, you can add the full URL to the issue
(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`).
```shell
git commit -m "this is my commit message. Ref #xxx"
```
or
```shell
git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/issues/<xxx>"
```
Of course, you can replace `gitlab.com` with the URL of your own GitLab instance.
**Note:** Linking your first commit to your issue is going to be relevant
for tracking your process far ahead with
[GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/)).
It will measure the time taken for planning the implementation of that issue,
which is the time between creating an issue and making the first commit.
## From Related Issues
Mentioning related issues in merge requests and other issues is useful
for your team members and collaborators to know that there are opened
issues around that same idea.
You do that as explained above, when
[mentioning an issue from a commit message](#from-commit-messages).
When mentioning the issue "A" in a issue "B", the issue "A" will also
display a notification in its tracker. The same is valid for mentioning
issues in merge requests.
![issue mentioned in issue](img/mention_in_issue.png)
## From Merge Requests
Mentioning issues in merge request comments work exactly the same way
they do for [related issues](#from-related-issues).
When you mention an issue in a merge request description, you can either
[close the issue as soon as the merge request is merged](closing_issues.md#via-merge-request),
or simply link both issue and merge request as described in the
[closing issues documentation](closing_issues.md#from-related-issues).
![issue mentioned in MR](img/mention_in_merge_request.png)
### Close an issue by merging a merge request
To [close an issue when a merge request is merged](closing_issues.md#via-merge-request), use the [automatic issue closing patern](automatic_issue_closing.md).
......@@ -2,6 +2,8 @@
> [Introduced][ce-3614] in GitLab 8.7.
Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
Due dates can be used in issues to keep track of deadlines and make sure
features are shipped on time. Due dates require at least [Reporter permissions][permissions]
to be able to edit them. On the contrary, they can be seen by everybody.
......@@ -22,8 +24,8 @@ Changes are saved immediately.
## Making use of due dates
Issues that have a due date can be distinctively seen in the issues index page
with a calendar icon next to them. Issues where the date is past due will have
Issues that have a due date can be distinctively seen in the issue tracker
displaying a date next to them. Issues where the date is overdue will have
the icon and the date colored red. You can sort issues by those that are
_Due soon_ or _Due later_ from the dropdown menu in the right.
......
doc/user/project/issues/img/confidential_issues_create.png

9.43 KB | W: | H:

doc/user/project/issues/img/confidential_issues_create.png

7.99 KB | W: | H:

doc/user/project/issues/img/confidential_issues_create.png
doc/user/project/issues/img/confidential_issues_create.png
doc/user/project/issues/img/confidential_issues_create.png
doc/user/project/issues/img/confidential_issues_create.png
  • 2-up
  • Swipe
  • Onion skin
doc/user/project/issues/img/confidential_issues_index_page.png

9.72 KB | W: | H:

doc/user/project/issues/img/confidential_issues_index_page.png

8.15 KB | W: | H:

doc/user/project/issues/img/confidential_issues_index_page.png
doc/user/project/issues/img/confidential_issues_index_page.png
doc/user/project/issues/img/confidential_issues_index_page.png
doc/user/project/issues/img/confidential_issues_index_page.png
  • 2-up
  • Swipe
  • Onion skin
doc/user/project/issues/img/confidential_issues_issue_page.png

15.7 KB | W: | H:

doc/user/project/issues/img/confidential_issues_issue_page.png

13.9 KB | W: | H:

doc/user/project/issues/img/confidential_issues_issue_page.png
doc/user/project/issues/img/confidential_issues_issue_page.png
doc/user/project/issues/img/confidential_issues_issue_page.png
doc/user/project/issues/img/confidential_issues_issue_page.png
  • 2-up
  • Swipe
  • Onion skin
doc/user/project/issues/img/confidential_issues_search_guest.png

9.78 KB | W: | H:

doc/user/project/issues/img/confidential_issues_search_guest.png

8.39 KB | W: | H:

doc/user/project/issues/img/confidential_issues_search_guest.png
doc/user/project/issues/img/confidential_issues_search_guest.png
doc/user/project/issues/img/confidential_issues_search_guest.png
doc/user/project/issues/img/confidential_issues_search_guest.png
  • 2-up
  • Swipe
  • Onion skin
doc/user/project/issues/img/confidential_issues_system_notes.png

2.95 KB | W: | H:

doc/user/project/issues/img/confidential_issues_system_notes.png

2.28 KB | W: | H:

doc/user/project/issues/img/confidential_issues_system_notes.png
doc/user/project/issues/img/confidential_issues_system_notes.png
doc/user/project/issues/img/confidential_issues_system_notes.png
doc/user/project/issues/img/confidential_issues_system_notes.png
  • 2-up
  • Swipe
  • Onion skin
doc/user/project/issues/img/due_dates_create.png

7.52 KB | W: | H:

doc/user/project/issues/img/due_dates_create.png

6.83 KB | W: | H:

doc/user/project/issues/img/due_dates_create.png
doc/user/project/issues/img/due_dates_create.png
doc/user/project/issues/img/due_dates_create.png
doc/user/project/issues/img/due_dates_create.png
  • 2-up
  • Swipe
  • Onion skin
doc/user/project/issues/img/due_dates_edit_sidebar.png

2.37 KB | W: | H:

doc/user/project/issues/img/due_dates_edit_sidebar.png

1.66 KB | W: | H:

doc/user/project/issues/img/due_dates_edit_sidebar.png
doc/user/project/issues/img/due_dates_edit_sidebar.png
doc/user/project/issues/img/due_dates_edit_sidebar.png
doc/user/project/issues/img/due_dates_edit_sidebar.png
  • 2-up
  • Swipe
  • Onion skin
doc/user/project/issues/img/due_dates_issues_index_page.png

20.9 KB | W: | H:

doc/user/project/issues/img/due_dates_issues_index_page.png

18.8 KB | W: | H:

doc/user/project/issues/img/due_dates_issues_index_page.png
doc/user/project/issues/img/due_dates_issues_index_page.png
doc/user/project/issues/img/due_dates_issues_index_page.png
doc/user/project/issues/img/due_dates_issues_index_page.png
  • 2-up
  • Swipe
  • Onion skin
doc/user/project/issues/img/due_dates_todos.png

5.51 KB | W: | H:

doc/user/project/issues/img/due_dates_todos.png

4.69 KB | W: | H:

doc/user/project/issues/img/due_dates_todos.png
doc/user/project/issues/img/due_dates_todos.png
doc/user/project/issues/img/due_dates_todos.png
doc/user/project/issues/img/due_dates_todos.png
  • 2-up
  • Swipe
  • Onion skin
# GitLab Issues Documentation
The GitLab Issue Tracker is an advanced and complete tool
for tracking the evolution of a new idea or the process
of solving a problem.
It allows you, your team, and your collaborators to share
and discuss proposals, before and while implementing them.
Issues and the GitLab Issue Tracker are available in all
[GitLab Products](https://about.gitlab.com/products/) as
part of the [GitLab Workflow](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/).
## Use-Cases
Issues can have endless applications. Just to exemplify, these are
some cases for which creating issues are most used:
- Discussing the implementation of a new idea
- Submitting feature proposals
- Asking questions
- Reporting bugs and malfunction
- Obtaining support
- Elaborating new code implementations
See also the blog post [Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/).
## Issue Tracker
The issue tracker is the collection of opened and closed issues created in a project.
![Issue tracker](img/issue_tracker.png)
Find the issue tracker by navigating to your **Project's Dashboard** > **Issues**.
## GitLab Issues Functionalities
The image bellow illustrates how an issue looks like:
![Issue view](img/issues_main_view.png)
Learn more about it on the [GitLab Issues Functionalities documentation](issues_functionalities.md).
## New Issue
Read through the [documentation on creating issues](create_new_issue.md).
## Closing issues
Read through the distinct ways to [close issues](closing_issues.md) on GitLab.
## Search for an issue
Learn how to [find an issue](../../search/index.md) by searching for and filtering them.
## Advanced features
### Confidential Issues
Whenever you want to keep the discussion presented in a
issue within your team only, you can make that
[issue confidential](confidential_issues.md). Even if your project
is public, that issue will be preserved. The browser will
respond with a 404 error whenever someone who is not a project
member with at least [Reporter level](../../permissions.md#project) tries to
access that issue's URL.
Learn more about them on the [confidential issues documentation](confidential_issues.md).
### Issue templates
Create templates for every new issue. They will be available from
the dropdown menu **Choose a template** when you create a new issue:
![issue template](img/issue_template.png)
Learn more about them on the [issue templates documentation](../../project/description_templates.md#creating-issue-templates).
### Crosslinking issues
Learn more about [crosslinking](crosslinking_issues.md) issues and merge requests.
### GitLab Issue Board
The [GitLab Issue Board](https://about.gitlab.com/features/issueboard/) is a way to
enhance your workflow by organizing and prioritizing issues in GitLab.
![Issue board](img/issue_board.png)
Find GitLab Issue Boards by navigating to your **Project's Dashboard** > **Issues** > **Board**.
Read through the documentation for [Issue Boards](../issue_board.md)
to find out more about this feature.
[Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-boards)
are available only in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/).
### Issue's API
Read through the [API documentation](../../../api/issues.md).
# GitLab Issues Functionalities
Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
## Issues Functionalities
The image bellow illustrates how an issue looks like:
![Issue view](img/issues_main_view_numbered.png)
You can find all the information on that issue on one screen.
### Issue screen
An issue starts with its status (open or closed), followed by its author,
and includes many other functionalities, numbered on the image above to
explain what they mean, one by one.
#### 1. New Issue, close issue, edit
- 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.
#### 2. Todos
- Add todo: add that issue to your [GitLab Todo](../../../workflow/todos.html) list
- Mark done: mark that issue as done (reflects on 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.
> **Tip:**
if a user is not member of that project, it can only be
assigned to them if they created the issue themselves.
#### 4. Milestone
- Select a [milestone](../milestones/index.md) to attribute that issue to.
#### 5. Time Tracking (EES/EEP)
This feature is available only in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/).
- Estimate time: add an estimate time in which the issue will be implemented
- Spend: add the time spent on the implementation of that issue
> **Note:**
both estimate and spend times are set via [GitLab Slash Commands](../slash_commands.md).
Learn more on the [Time Tracking documentation](https://docs.gitlab.com/ee/workflow/time_tracking.html).
#### 6. Due date
When you work on a tight schedule, and it's important to
have a way to setup a deadline for implementations and for solving
problems. This can be facilitated by the [due date](due_dates.md)). Due dates
can be changed as many times as needed.
#### 7. Labels
Categorize issues by giving them [labels](../labels.md). They help to
organize team's workflows, once they enable you to work with the
[GitLab Issue Board](index.md#gitlab-issue-board).
Group Labels, which allow you to use the same labels per
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.
> **Tip:**
if the label doesn't exist yet, when you click **Edit**, it opens a dropdown menu from which you can select **Create new label**.
#### 8. Weight (EES/EEP)
Issue Weights are only available in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/).
- Attribute a weight (in a 0 to 9 range) to that issue. Easy to complete
should weight 1 and very hard to complete should weight 9.
Learn more on the [Issue Weight documentation](https://docs.gitlab.com/ee/workflow/issue_weight.html).
#### 9. Participants
- People involved in that issue (mentioned in the description or in the [discussion](../../discussions/index.md)).
#### 10. 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
longer want to receive them, unsubscribe to it.
Read more on the [notifications documentation](../../../workflow/notifications.md#issue-merge-request-events).
#### 11. Reference
- A quick "copy to clipboard" button to 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.
#### 12. Title and description
- Title: a plain text title describing the issue's subject.
- Description: a text field which fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
#### 13. @mentions
- Mentions: you can either `@mention` a user or a group present in your
GitLab instance and they will be notified via todos and email, unless that
person has disabled all notifications in their profile settings.
To change your [notification settings](../../../workflow/notifications.md) navigate to
**Profile Settings** > **Notifications** > **Global notification level**
and choose your preferences from the dropdown menu.
> **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.
#### 14. Related Merge Requests
- Any merge requests mentioned in that issue's description
or in the issue thread.
#### 15. Award emoji
- Award an emoji to that issue.
> **Tip:**
Posting "+1" as comments in threads spam all
participants of that issue. Awarding an emoji is a way to let them
know you like it without spamming them.
#### 16. Thread
- 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).
#### 17. Comment, start a discusion, or comment and close
Once you wrote your comment, you can either:
- 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.
#### 18. New branch
- [New branch](../repository/web_editor.md#create-a-new-branch-from-an-issue):
create a new branch, followed by a new merge request which will automatically close that
issue as soon as that merge request is merged.
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