Skip to content

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

Merge branch 'docs-similar-issues-edit' into 'master' 

Docs: Full Copy Edit and Refactor of Issues docs

Closes #60767

See merge request gitlab-org/gitlab-ce!27553
parents c55bbef9 4efc8574
Hide whitespace changes
Inline Side-by-side
Showing with 350 additions and 377 deletions
doc/README.md
View file @ 19dc1105
......@@ -111,7 +111,7 @@ The following documentation relates to the DevOps **Plan** stage:
| [Discussions](user/discussions/index.md) | Threads, comments, and resolvable discussions in issues, commits, and merge requests. |
| [Due Dates](user/project/issues/due_dates.md) | Keep track of issue deadlines. |
| [Epics](user/group/epics/index.md) **[ULTIMATE]** | Tracking groups of issues that share a theme. |
| [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/moving_issues.md) | Project issues, restricting access to issues, create templates for submitting new issues and merge requests, and moving issues between projects. |
| [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/managing_issues.md#moving-issues) | Project issues, restricting access to issues, create templates for submitting new issues and merge requests, and moving issues between projects. |
| [Labels](user/project/labels.md) | Categorize issues or merge requests with descriptive labels. |
| [Milestones](user/project/milestones/index.md) | Set milestones for delivery of issues and merge requests, with optional due date. |
| [Project Issue Board](user/project/issue_board.md) | Display issues on a Scrum or Kanban board. |
......
doc/administration/incoming_email.md
View file @ 19dc1105
......@@ -4,7 +4,7 @@ GitLab has several features based on receiving incoming emails:
- [Reply by Email](reply_by_email.md): allow GitLab users to comment on issues
and merge requests by replying to notification emails.
- [New issue by email](../user/project/issues/create_new_issue.md#new-issue-via-email):
- [New issue by email](../user/project/issues/managing_issues.md#new-issue-via-email):
allow GitLab users to create a new issue by sending an email to a
user-specific email address.
- [New merge request by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email):
......
doc/administration/index.md
View file @ 19dc1105
......@@ -117,7 +117,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
- Instances. **[PREMIUM ONLY]**
- [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. **[PREMIUM ONLY]**
- [Incoming email](incoming_email.md): Configure incoming emails to allow
users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/create_new_issue.md#new-issue-via-email) and
users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#new-issue-via-email) and
[merge requests by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email), and to enable [Service Desk](../user/project/service_desk.md).
- [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a
basic Postfix mail server with IMAP authentication on Ubuntu for incoming
......
doc/administration/issue_closing_pattern.md
View file @ 19dc1105
# Issue closing pattern
# Issue closing pattern **[CORE ONLY]**
>**Note:**
This is the administration documentation.
......@@ -46,4 +46,4 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by
[gitlab.yml.example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example
[reconfigure]: restart_gitlab.md#omnibus-gitlab-reconfigure
[restart]: restart_gitlab.md#installations-from-source
[user documentation]: ../user/project/issues/automatic_issue_closing.md
[user documentation]: ../user/project/issues/managing_issues.md#closing-issues-automatically
doc/customization/issue_closing.md
View file @ 19dc1105
---
redirect_to: '../user/project/issues/automatic_issue_closing.md'
redirect_to: '../user/project/issues/managing_issues.md#closing-issues-automatically'
---
This document was moved to [another location](../user/project/issues/managing_issues.md#closing-issues-automatically).
doc/development/contributing/merge_request_workflow.md
View file @ 19dc1105
......@@ -65,7 +65,7 @@ request is as follows:
1. If you are contributing documentation, choose `Documentation` from the
"Choose a template" menu and fill in the description according to the template.
1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or
`Closes #XXX` syntax to [auto-close](../../user/project/issues/automatic_issue_closing.md)
`Closes #XXX` syntax to [auto-close](../../user/project/issues/managing_issues.md#closing-issues-automatically)
the issue(s) once the merge request is merged.
1. If you're allowed to (Core team members, for example), set a relevant milestone
and [labels](issue_workflow.md).
......
doc/gitlab-basics/README.md
View file @ 19dc1105
......@@ -22,7 +22,7 @@ The following are guides to basic GitLab functionality:
- [Fork a project](fork-project.md), to duplicate projects so they can be worked on in parallel.
- [Add a file](add-file.md), to add new files to a project's repository.
- [Add an image](add-image.md), to add new images to a project's repository.
- [Create an issue](../user/project/issues/create_new_issue.md), to start collaborating within a project.
- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue), to start collaborating within a project.
- [Create a merge request](add-merge-request.md), to request changes made in a branch be merged into a project's repository.
- See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE) and [GitLab Flow page](../workflow/gitlab_flow.md).
......
doc/gitlab-basics/create-issue.md
View file @ 19dc1105
---
redirect_to: '../user/project/issues/index.md#issue-actions'
redirect_to: '../user/project/issues/index.md#viewing-and-managing-issues'
---
This document was moved to [another location](../user/project/issues/index.md#issue-actions).
This document was moved to [another location](../user/project/issues/index.md#viewing-and-managing-issues).
doc/intro/README.md
View file @ 19dc1105
......@@ -15,7 +15,7 @@ Create projects and groups.
Create issues, labels, milestones, cast your vote, and review issues.
- [Create an issue](../user/project/issues/create_new_issue.md)
- [Create an issue](../user/project/issues/managing_issues.md#create-a-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)
......@@ -26,7 +26,7 @@ Create merge requests and review code.
- [Fork a project and contribute to it](../workflow/forking_workflow.md)
- [Create a new merge request](../gitlab-basics/add-merge-request.md)
- [Automatically close issues from merge requests](../user/project/issues/automatic_issue_closing.md)
- [Automatically close issues from merge requests](../user/project/issues/managing_issues.md#closing-issues-automatically)
- [Automatically merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md)
- [Revert any commit](../user/project/merge_requests/revert_changes.md)
- [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md)
......
doc/user/project/cycle_analytics.md
View file @ 19dc1105
......@@ -156,6 +156,6 @@ Learn more about Cycle Analytics in the following resources:
[environment]: ../../ci/yaml/README.md#environment
[GitLab flow]: ../../workflow/gitlab_flow.md
[idea to production]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab
[issue closing pattern]: issues/automatic_issue_closing.md
[issue closing pattern]: issues/managing_issues.md#closing-issues-automatically
[permissions]: ../permissions.md
[yml]: ../../ci/yaml/README.md
doc/user/project/issues/automatic_issue_closing.md
View file @ 19dc1105
# Automatic issue closing
>**Notes:**
>
> - This is the user docs. In order to change the default issue closing pattern,
> follow the steps in the [administration docs].
> - For performance reasons, automatic issue closing is disabled for the very
> first push from an existing repository.
When a commit or merge request resolves one or more issues, it is possible to
automatically have these issues closed when the commit or merge request lands
in the project's default branch.
If a commit message or merge request description contains a sentence matching
a certain regular expression, all issues referenced from the matched text will
be closed. This happens when the commit is pushed to a project's
[**default** branch](../repository/branches/index.md#default-branch), or when a
commit or merge request is merged into it.
## Default closing pattern value
When not specified, the default issue closing pattern as shown below will be
used:
```bash
((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+)
```
Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's
source code that can match references to:
- A local issue (`#123`).
- A cross-project issue (`group/project#123`).
- A link to an issue
(`https://gitlab.example.com/group/project/issues/123`).
---
This translates to the following keywords:
- Close, Closes, Closed, Closing, close, closes, closed, closing
- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
- Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing
redirect_to: 'managing_issues.md#closing-issues-automatically'
---
For example the following commit message:
```
Awesome commit message
Fix #20, Fixes #21 and Closes group/otherproject#22.
This commit is also related to #17 and fixes #18, #19
and https://gitlab.example.com/group/otherproject/issues/23.
```
will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed
to, as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as
it does not match the pattern. It works with multi-line commit messages as well
as one-liners when used with `git commit -m`.
[administration docs]: ../../../administration/issue_closing_pattern.md
This document was moved to [another location](managing_issues.md#closing-issues-automatically).
doc/user/project/issues/closing_issues.md
View file @ 19dc1105
# Closing Issues
---
redirect_to: 'managing_issues.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 dragging 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 pattern
Alternatively, a GitLab **administrator** can
[customize the issue closing pattern](../../../administration/issue_closing_pattern.md).
This document was moved to [another location](managing_issues.md#closing-issues).
doc/user/project/issues/create_new_issue.md
View file @ 19dc1105
# Create a new Issue
---
redirect_to: 'managing_issues.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 [issue data and actions documentation](issue_data_and_actions.md#parts-of-an-issue)
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)
## New issue via email
At the bottom of a project's Issues List page, a link to **Email a new issue to this project**
is displayed if your GitLab instance has [incoming email](../../../administration/incoming_email.md) configured.
![Bottom of a project issues page](img/new_issue_from_email.png)
When you click this link, an email address is displayed which belongs to you for creating issues in this project.
You can save this address as a contact in your email client for easy acceess.
CAUTION: **Caution:**
This is a private email address, generated just for you. **Keep it to yourself**,
as anyone who gets ahold of it can create issues or merge requests as if they
were you. If the address is compromised, or you'd like it to be regenerated for
any reason, click **Email a new issue to this project** again and click the reset link.
Sending an email to this address will create a new issue on your behalf for
this project, where:
- The email subject becomes the issue title.
- The email body becomes the issue description.
- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported.
NOTE: **Note:**
In GitLab 11.7, we updated the format of the generated email address.
However the older format is still supported, allowing existing aliases
or contacts to continue working._
## New issue via Service Desk **[PREMIUM]**
Enable [Service Desk](../service_desk.md) to your project and offer email support.
By doing so, when your customer sends a new email, a new issue can be created in
the appropriate project and followed up from there.
## New issue from the group-level Issue Tracker
Head to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker
for all projects in your Group. Select the project you'd like to add an issue for
using the dropdown button at the top-right of the page.
![Select project to create issue](img/select_project_from_group_level_issue_tracker.png)
We'll keep track of the project you selected most recently, and use it as the default
for your next visit. This should save you a lot of time and clicks, if you mostly
create issues for the same project.
![Create issue from group-level issue tracker](img/create_issue_from_group_level_issue_tracker.png)
## New issue via URL with prefilled fields
You can link directly to the new issue page for a given project, with prefilled
field values using query string parameters in a URL. This is useful for embedding
a URL in an external HTML page, and also certain scenarios where you want the user to
create an issue with certain fields prefilled.
The title, description, and description template fields can be prefilled using
this method. The description and description template fields cannot be pre-entered
in the same URL (since a description template just populates the description field).
Follow these examples to form your new issue URL with prefilled fields.
- For a new issue in the GitLab Community Edition project with a pre-entered title
and a pre-entered description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea`
- For a new issue in the GitLab Community Edition project with a pre-entered title
and a pre-entered description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal`
This document was moved to [another location](managing_issues.md#create-a-new-issue).
doc/user/project/issues/crosslinking_issues.md
View file @ 19dc1105
......@@ -25,9 +25,8 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam
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/)).
NOTE: **Note:** Linking your first commit to your issue is going to be relevant
for tracking your process 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.
......@@ -35,14 +34,13 @@ which is the time between creating an issue and making the first commit.
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.
issues regarding the same topic.
You do that as explained above, when
[mentioning an issue from a commit message](#from-commit-messages).
You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages).
When mentioning the issue "A" in issue "B", the issue "A" will also
display a notification in its tracker. The same is valid for mentioning
issues in merge requests.
When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification
in its tracker. That is, you only need to mention the relationship once for it to
display in both issues. The same is valid when mentioning issues in [merge requests](#from-merge-requests).
![issue mentioned in issue](img/mention_in_issue.png)
......@@ -53,10 +51,7 @@ they do for [related issues](#from-related-issues).
When you mention an issue in a merge request description, it will simply
[link the issue and merge request together](#from-related-issues). Additionally,
you can also [set an issue to close as soon as the merge request is merged](closing_issues.md#via-merge-request).
you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically)
as soon as the merge request is merged.
![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 pattern](automatic_issue_closing.md).
doc/user/project/issues/csv_import.md
View file @ 19dc1105
......@@ -7,7 +7,8 @@ Issues can be imported to a project by uploading a CSV file with the columns
The user uploading the CSV file will be set as the author of the imported issues.
> **Note:** A permission level of `Developer` or higher is required to import issues.
NOTE: **Note:** A permission level of [Developer](../../permissions.md), or higher, is required
to import issues.
## Prepare for the import
......@@ -24,34 +25,38 @@ To import issues:
1. Select the file and click the **Import issues** button.
The file is processed in the background and a notification email is sent
to you once the import is completed.
to you once the import is complete.
## CSV file format
### Header row
Sample CSV file data:
CSV files must contain a header row where the first column header is `title` and the second is `description`.
If additional columns are present, they will be ignored.
### Column separator
### Header row
The column separator is automatically detected from the header row.
CSV files must contain a header row beginning with at least two columns, `title` and
`description`, in that order. If additional columns are present, they will be ignored.
Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`).
### Separators
### Row separator
The column separator is automatically detected from the header row. Supported separator
characters are: commas (`,`), semicolons (`;`), and tabs (`\t`).
Lines ending in either `CRLF` or `LF` are supported.
The row separator can be either `CRLF` or `LF`.
### Quote character
The double-quote (`"`) character is used to quote fields so you can use the column separator within a field. To insert
a double-quote (`"`) within a quoted field, use two double-quote characters in succession, i.e. `""`.
The double-quote (`"`) character is used to quote fields, enabling the use of the column
separator within a field (see the third line in the [sample CSV](#csv-file-format)).
To insert a double-quote (`"`) within a quoted field, use two double-quote characters
in succession, i.e. `""`.
### Data rows
After the header row, succeeding rows must follow the same column order. The issue title is required while the
description is optional.
After the header row, succeeding rows must follow the same column order. The issue
title is required while the description is optional.
### File size
......
doc/user/project/issues/deleting_issues.md
View file @ 19dc1105
# Deleting Issues
---
redirect_to: 'managing_issues.md#deleting-issues'
---
> [Introduced][ce-2982] in GitLab 8.6
Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
You can delete an issue by editing it and clicking on the delete button.
![delete issue - button](img/delete_issue.png)
>**Note:** Only [project owners](../../permissions.md) can delete issues.
[ce-2982]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2982
\ No newline at end of file
This document was moved to [another location](managing_issues.md#deleting-issues).
doc/user/project/issues/due_dates.md
View file @ 19dc1105
......@@ -4,30 +4,32 @@
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.md#project-members-permissions)
to be able to edit them. On the contrary, they can be seen by everybody.
Due dates can be used in issues to keep track of deadlines and make sure features are
shipped on time. Users must have at least [Reporter permissions](../../permissions.md)
to be able to edit them, but they can be seen by everybody with permission to view
the issue.
## Setting a due date
When creating or editing an issue, you can see the due date field from where
a calendar will appear to help you choose the date you want. To remove it,
select the date text and delete it.
When creating or editing an issue, you can click in the **due date** field and a calendar
will appear to help you choose the date you want. To remove the date, select the date
text and delete it. The date is related to the server's timezone, not the timezone of
the user setting the due date.
![Create a due date](img/due_dates_create.png)
A quicker way to set a due date is via the issue sidebar. Simply expand the
sidebar and select **Edit** to pick a due date or remove the existing one.
You can also set a due date via the issue sidebar. Expand the
sidebar and click **Edit** to pick a due date or remove the existing one.
Changes are saved immediately.
![Edit a due date via the sidebar](img/due_dates_edit_sidebar.png)
## Making use of due dates
Issues that have a due date can be distinctively seen in the issue tracker
Issues that have a due date can be easily 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.
`Due soon` or `Due later` from the dropdown menu on the right.
![Issues with due dates in the issues index page](img/due_dates_issues_index_page.png)
......@@ -36,14 +38,13 @@ Due dates also appear in your [todos list](../../../workflow/todos.md).
![Issues with due dates in the todos](img/due_dates_todos.png)
The day before an open issue is due, an email will be sent to all participants
of the issue. Both the due date and the day before are calculated using the
server's timezone.
of the issue. Like the due date, the "day before the due date" is determined by the
server's timezone, ignoring the participants' timezones.
Issues with due dates can also be exported as an iCalendar feed. The URL of the
feed can be added to calendar applications. The feed is accessible by clicking
on the _Subscribe to calendar_ button on the following pages:
feed can be added to many calendar applications. The feed is accessible by clicking
on the **Subscribe to calendar** button on the following pages:
- on the **Assigned Issues** page that is linked on the right-hand side of the
GitLab header
- on the **Assigned Issues** page that is linked on the right-hand side of the GitLab header
- on the **Project Issues** page
- on the **Group Issues** page
doc/user/project/issues/index.md
View file @ 19dc1105
......@@ -6,8 +6,9 @@ Issues are the fundamental medium for collaborating on ideas and planning work i
The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems, and planning work.
Issues can allow you, your team, and your collaborators to share and discuss proposals before and during their implementation.
However, they can be used for a variety of other purposes, customized to your needs and workflow.
Issues can allow you, your team, and your collaborators to share and discuss proposals
before, and during, their implementation. However, they can be used for a variety of
other purposes, customized to your needs and workflow.
Issues are always associated with a specific project, but if you have multiple projects in a group,
you can also view all the issues collectively at the group level.
......@@ -17,13 +18,15 @@ you can also view all the issues collectively at the group level.
- Discussing the implementation of a new idea
- Tracking tasks and work status
- Accepting feature proposals, questions, support requests, or bug reports
- Elaborating new code implementations
- Elaborating on 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/)".
See also [Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/).
## Parts of an issue
Issues contain a variety of content and metadata, enabling a large range of flexibility in how they are used. Each issue can contain the following attributes, though some items may remain unset.
Issues contain a variety of content and metadata, enabling a large range of flexibility
in how they are used. Each issue can contain the following attributes, though not all items
must be set.
<table class="borderless-table fixed-table">
<tr>
......@@ -70,23 +73,36 @@ Issues contain a variety of content and metadata, enabling a large range of flex
## Viewing and managing issues
While you can view and manage the full detail of an issue at its URL, you can also work with multiple issues at a time using the Issues List, Issue Boards, Epics **[ULTIMATE]**, and issue references.
While you can view and manage the full details of an issue on the [issue page](#issue-page),
you can also work with multiple issues at a time using the [Issues List](#issues-list),
[Issue Boards](#issue-boards), Issue references, and [Epics](#epics-ultimate)**[ULTIMATE]**.
Key actions for Issues include:
- [Creating issues](managing_issues.md#create-a-new-issue)
- [Moving issues](managing_issues.md#moving-issues)
- [Closing issues](managing_issues.md#closing-issues)
- [Deleting issues](managing_issues.md#deleting-issues)
### Issue page
![Issue view](img/issues_main_view.png)
On an issue’s page, you can view all aspects of the issue, and you can also modify them if you you have the necessary [permissions](../../permissions.md).
For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page.
On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md),
and modify them if you you have the necessary [permissions](../../permissions.md).
### Issues list
![Project issues list view](img/project_issues_list_view.png)
On the Issues List, you can view all issues in the current project, or from multiple projects when opening the Issues List from the higher-level group context. Filter the issue list by [any search query](../../search/index.md#issues-and-merge-requests-per-project) and/or specific metadata, such as label(s), assignees(s), status, and more. From this view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues.
On the Issues List, you can view all issues in the current project, or from multiple
projects when opening the Issues List from the higher-level group context. Filter the
issue list with a [search query](../../search/index.md#issues-and-merge-requests-per-project),
including specific metadata, such as label(s), assignees(s), status, and more. From this
view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues.
For more information on interacting with Issues, see the [Issue Data and Actions](issue_data_and_actions.md) page.
For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page
for a rundown of all the fields and information in an issue.
For sorting by issue priority, see [Label Priority](../labels.md#label-priority).
......@@ -94,44 +110,55 @@ For sorting by issue priority, see [Label Priority](../labels.md#label-priority)
![Issue board](img/issue_board.png)
Issue boards are Kanban boards with columns that display issues based on their labels or their assignees**[PREMIUM]**. They offer the flexibility to manage issues using highly customizable workflows.
[Issue boards](../issue_board.md) are Kanban boards with columns that display issues based on their labels
or their assignees**[PREMIUM]**. They offer the flexibility to manage issues using
highly customizable workflows.
You can reorder issues within a column, or drag an issue card to another column; its associated label or assignee will change to match that of the new column. The entire board can also be filtered to only include issues from a certain milestone or an overarching label.
For more information, see the [Issue Boards](../issue_board.md) page.
You can reorder issues within a column. If you drag an issue card to another column, its
associated label or assignee will change to match that of the new column. The entire
board can also be filtered to only include issues from a certain milestone or an overarching
label.
### Epics **[ULTIMATE]**
Epics let you manage your portfolio of projects more efficiently and with less effort by tracking groups of issues that share a theme, across projects and milestones.
For more information, see the [Epics](../../group/epics/index.md) page.
[Epics](../../group/epics/index.md) let you manage your portfolio of projects more
efficiently and with less effort by tracking groups of issues that share a theme, across
projects and milestones.
### Related issues **[STARTER]**
You can mark two issues as related, so that when viewing each one, the other is always listed in its Related Issues section. This can help display important context, such as past work, dependencies, or duplicates.
For more information, see [Related Issues](related_issues.md).
You can mark two issues as related, so that when viewing one, the other is always
listed in its [Related Issues](related_issues.md) section. This can help display important
context, such as past work, dependencies, or duplicates.
### Crosslinking issues
When you reference an issue from another issue or merge request by including its URL or ID, the referenced issue displays a message in the Activity stream about the reference, with a link to the other issue or MR.
You can [crosslink issues](crosslinking_issues.md) by referencing an issue from another
issue or merge request by including its URL or ID. The referenced issue displays a
message in the Activity stream about the reference, with a link to the other issue or MR.
For more information, see [Crosslinking issues](crosslinking_issues.md).
### Similar issues
## Issue actions
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866) in GitLab 11.6.
- [Create an issue](create_new_issue.md)
- [Create an issue from a template](../../project/description_templates.md#using-the-templates)
- [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#22-create-merge-request)
To prevent duplication of issues for the same topic, GitLab searches for similar issues
when new issues are being created.
When typing in the title in the new issue form, GitLab searches titles and descriptions
across all issues the user has access to in the current project. Up 5 similar issues,
sorted by most recently updated, are displayed below the title box. Note that this feature
requires [GraphQL](../../../api/graphql/index.md) to be enabled.
## Advanced issue management
![Similar issues](img/similar_issues.png)
- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues in order to change their status, assignee, milestone, or labels in bulk.
## Other Issue actions
- [Create an issue from a template](../../project/description_templates.md#using-the-templates)
- [Set a due date](due_dates.md)
- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues
in order to change their status, assignee, milestone, or labels in bulk.
- [Import issues](csv_import.md)
- [Export issues](csv_export.md) **[STARTER]**
- [Issues API](../../../api/issues.md)
- Configure an [external issue tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine,
or Bugzilla.
- Configure an [external issue tracker](../../../integration/external-issue-tracker.md)
such as Jira, Redmine, or Bugzilla.
doc/user/project/issues/issue_data_and_actions.md
View file @ 19dc1105
......@@ -48,7 +48,7 @@ which you can click to mark that issue as done (which will be reflected in the T
#### 3. Assignee
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
The assignee(s) can be changed as often 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.
......
doc/user/project/issues/managing_issues.md 0 → 100644
View file @ 19dc1105
# Managing Issues
[GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and
planning work in GitLab. [Creating](#create-a-new-issue), [moving](#moving-issues),
[closing](#closing-issues), and [deleting](#deleting-issues) are key actions that
you can do with issues.
## Create a new Issue
When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md#parts-of-an-issue), as illustrated below.
![New issue from the issues list](img/new_issue.png)
### Accessing the new Issue form
There are many ways to get to the new Issue form from within a project:
- Navigate to your **Project's Dashboard** > **Issues** > **New Issue**:
![New issue from the issue list view](img/new_issue_from_tracker_list.png)
- 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)
- 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)
- From an **Issue Board**, create a new issue by clicking on the plus sign (**+**) at the top of a list.
It opens a new issue for that project, pre-labeled with its respective list.
![From the issue board](img/new_issue_from_issue_board.png)
### New issue from the group-level Issue Tracker
Go to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker
for all projects in your Group. Select the project you'd like to add an issue for
using the dropdown button at the top-right of the page.
![Select project to create issue](img/select_project_from_group_level_issue_tracker.png)
We'll keep track of the project you selected most recently, and use it as the default
for your next visit. This should save you a lot of time and clicks, if you mostly
create issues for the same project.
![Create issue from group-level issue tracker](img/create_issue_from_group_level_issue_tracker.png)
### New issue via Service Desk **[PREMIUM]**
Enable [Service Desk](../service_desk.md) for your project and offer email support.
By doing so, when your customer sends a new email, a new issue can be created in
the appropriate project and followed up from there.
### New issue via email
A link to **Email a new issue to this project** is displayed at the bottom of a project's
**Issues List** page, if your GitLab instance has [incoming email](../../../administration/incoming_email.md)
configured.
![Bottom of a project issues page](img/new_issue_from_email.png)
When you click this link, an email address is generated and displayed, which should be used
by **you only**, to create issues in this project. You can save this address as a
contact in your email client for easy acceess.
CAUTION: **Caution:**
This is a private email address, generated just for you. **Keep it to yourself**,
as anyone who knows it can create issues or merge requests as if they
were you. If the address is compromised, or you'd like it to be regenerated for
any reason, click **Email a new issue to this project** again and click the reset link.
Sending an email to this address will create a new issue in your name for
this project, where:
- The email subject becomes the issue title.
- The email body becomes the issue description.
- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported.
NOTE: **Note:**
In GitLab 11.7, we updated the format of the generated email address. However the
older format is still supported, allowing existing aliases or contacts to continue working.
### New issue via URL with prefilled fields
You can link directly to the new issue page for a given project, with prefilled
field values using query string parameters in a URL. This is useful for embedding
a URL in an external HTML page, and also certain scenarios where you want the user to
create an issue with certain fields prefilled.
The title, description, and description template fields can be prefilled using
this method. You cannot pre-fill both the description and description template fields
in the same URL (since a description template also populates the description field).
Follow these examples to form your new issue URL with prefilled fields.
- For a new issue in the GitLab Community Edition project with a pre-filled title
and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea`
- For a new issue in the GitLab Community Edition project with a pre-filled title
and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal`
## Moving Issues
Moving an issue will copy it to a new location (project), and close it in the old project,
but it will not be deleted. There will also be a system note added to both issues
indicating where it came from and went to.
The "Move issue" button is at the bottom of the right-sidebar when viewing the issue.
![move issue - button](img/sidebar_move_issue.png)
## Closing Issues
When you decide that an issue is resolved, or no longer needed, you can close the issue
using the close button:
![close issue - button](img/button_close_issue.png)
You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card
from its list and dropping it into the **Closed** list.
![close issue from the Issue Board](img/close_issue_from_board.gif)
### Closing issues automatically
NOTE: **Note:**
For performance reasons, automatic issue closing is disabled for the very first
push from an existing repository.
When a commit or merge request resolves one or more issues, it is possible to have
these issues closed automatically when the commit or merge request reaches the project's
default branch.
If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern),
all issues referenced in the matched text will be closed. This happens when the commit
is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch),
or when a commit or merge request is merged into it.
For example, if `Closes #4, #6, Related to #5` is included in a Merge Request
description, issues `#4` and `#6` will close automatically when the MR is merged, but not `#5`.
Using `Related to` flags `#5` as a [related issue](related_issues.md),
but it will not close automatically.
![merge request closing issue when merged](img/merge_request_closes_issue.png)
If the issue is in a different repository than the MR, add the full URL for the issue(s):
```md
Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx>
```
#### Default closing pattern
When not specified, the default issue closing pattern as shown below will be used:
```bash
((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+)
```
This translates to the following keywords:
- Close, Closes, Closed, Closing, close, closes, closed, closing
- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
- Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing
Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's
source code that can match references to:
- A local issue (`#123`).
- A cross-project issue (`group/project#123`).
- A link to an issue (`https://gitlab.example.com/group/project/issues/123`).
For example the following commit message:
```
Awesome commit message
Fix #20, Fixes #21 and Closes group/otherproject#22.
This commit is also related to #17 and fixes #18, #19
and https://gitlab.example.com/group/otherproject/issues/23.
```
will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to,
as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as it does
not match the pattern. It works with multi-line commit messages as well as one-liners
when used from the command line with `git commit -m`.
#### Customizing the issue closing pattern **[CORE ONLY]**
In order to change the default issue closing pattern, you must edit the
[`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md)
of your installation.
## Deleting Issues
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2982) in GitLab 8.6
Users with [project owner permission](../../permissions.md) can delete an issue by
editing it and clicking on the delete button.
![delete issue - button](img/delete_issue.png)
doc/user/project/issues/moving_issues.md
View file @ 19dc1105
# Moving Issues
Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
Moving an issue will close it and duplicate it on the specified project.
There will also be a system note added to both issues indicating where it came from or went to.
You can move an issue with the "Move issue" button at the bottom of the right-sidebar when viewing the issue.
![move issue - button](img/sidebar_move_issue.png)
## Troubleshooting
### Moving Issues in Bulk
If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**.
To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change **project**, **admin_user** and **target_project** to your values. We do also recommend [creating a backup](https://docs.gitlab.com/ee/raketasks/backup_restore.html#creating-a-backup-of-the-gitlab-system) before attempting any changes in the console.
```ruby
project = Project.find_by_full_path('full path of the project where issues are moved from')
issues = project.issues
admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues
target_project = Project.find_by_full_path('full path of target project where issues moved to')
issues.each do |issue|
if issue.state != "closed" && issue.moved_to.nil?
Issues::MoveService.new(project, admin_user).execute(issue, target_project)
else
puts "issue with id: #{issue.id} and title: #{issue.title} was not moved"
end
end; nil
```
---
redirect_to: 'managing_issues.md#moving-issues'
---
This document was moved to [another location](managing_issues.md#moving-issues).
doc/user/project/issues/similar_issues.md
View file @ 19dc1105
# Similar issues
---
redirect_to: 'index.md#similar-issues'
---
> [Introduced][ce-22866] in GitLab 11.6.
Similar issues suggests issues that are similar when new issues are being created.
This features requires [GraphQL] to be enabled.
![Similar issues](img/similar_issues.png)
You can see the similar issues when typing in the title in the new issue form.
This searches both titles and descriptions across all issues the user has access
to in the current project. It then displays the first 5 issues sorted by most
recently updated.
[GraphQL]: ../../../api/graphql/index.md
[ce-22866]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866
This document was moved to [another location](index.md#similar-issues).
doc/user/project/merge_requests/index.md
View file @ 19dc1105
......@@ -23,7 +23,7 @@ With GitLab merge requests, you can:
- Build, test, and deploy your code in a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md)
- Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests)
- View the deployment process through [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines)
- [Automatically close the issue(s)](../../project/issues/closing_issues.md#via-merge-request) that originated the implementation proposed in the merge request
- [Automatically close the issue(s)](../../project/issues/managing_issues.md#closing-issues-automatically) that originated the implementation proposed in the merge request
- Assign it to any registered user, and change the assignee how many times you need
- Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation
- Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md)
......
doc/user/project/repository/branches/index.md
View file @ 19dc1105
......@@ -21,7 +21,7 @@ branch for your project. You can choose another branch to be your project's
default under your project's **Settings > Repository**.
The default branch is the branch affected by the
[issue closing pattern](../../issues/automatic_issue_closing.md),
[issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically),
which means that _an issue will be closed when a merge request is merged to
the **default branch**_.
......
doc/user/project/repository/web_editor.md
View file @ 19dc1105
......@@ -114,7 +114,7 @@ If your [project is already configured with a deployment service][project-servic
After the branch is created, you can edit files in the repository to fix
the issue. When a merge request is created based on the newly created branch,
the description field will automatically display the [issue closing pattern]
the description field will automatically display the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically)
`Closes #ID`, where `ID` the ID of the issue. This will close the issue once the
merge request is merged.
......@@ -181,4 +181,3 @@ through the web editor, you can choose to use another of your linked email
addresses from the **User Settings > Edit Profile** page.
[ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808
[issue closing pattern]: ../issues/automatic_issue_closing.md
doc/workflow/README.md
View file @ 19dc1105
......@@ -4,7 +4,7 @@ comments: false
# Workflow
- [Automatic issue closing](../user/project/issues/automatic_issue_closing.md)
- [Automatic issue closing](../user/project/issues/managing_issues.md#closing-issues-automatically)
- [Change your time zone](timezone.md)
- [Cycle Analytics](../user/project/cycle_analytics.md)
- [Description templates](../user/project/description_templates.md)
......
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