diff options
| author | Evan Read <eread@gitlab.com> | 2019-07-04 00:55:35 +0000 |
|---|---|---|
| committer | Evan Read <eread@gitlab.com> | 2019-07-04 00:55:35 +0000 |
| commit | 19dc1105524e3d25821670706a750043775588fa (patch) | |
| tree | 1f6eae35a6a899c297473607db8c45b6706833b2 | |
| parent | c55bbef97534cabecd6427b7685ec0a7cc52ddd6 (diff) | |
| parent | 4efc8574cb45369797cf902d4e9676506a6e4cf7 (diff) | |
| download | gitlab-ce-19dc1105524e3d25821670706a750043775588fa.tar.gz | |
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
26 files changed, 350 insertions, 377 deletions
diff --git a/doc/README.md b/doc/README.md index 489c8117b9d..5eaa998a7b8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -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. | diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 8271c579f5b..84a34ae7d6e 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -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): diff --git a/doc/administration/index.md b/doc/administration/index.md index 602eecb9746..f480d18ea00 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -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 diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 160da47c780..9c352096ecc 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -1,4 +1,4 @@ -# 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 diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md index 680c51e7524..9333f55ca9c 100644 --- a/doc/customization/issue_closing.md +++ b/doc/customization/issue_closing.md @@ -1,3 +1,5 @@ --- -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). diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 6064f59ed10..ce5d9786e6e 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -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). diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md index 0c268eff9f1..fd16047b8e4 100644 --- a/doc/gitlab-basics/README.md +++ b/doc/gitlab-basics/README.md @@ -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). diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md index 6e2a09fc030..5fa5f1bf2e2 100644 --- a/doc/gitlab-basics/create-issue.md +++ b/doc/gitlab-basics/create-issue.md @@ -1,5 +1,5 @@ --- -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). diff --git a/doc/intro/README.md b/doc/intro/README.md index d9c733d4285..9a8cd925e48 100644 --- a/doc/intro/README.md +++ b/doc/intro/README.md @@ -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) diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index dc97a44fd68..5d36e1d4be3 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -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 diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index c3e06b219ff..dab79327d6a 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -1,63 +1,5 @@ -# 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). diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md index 1d88745af9f..04f1c8e1a4a 100644 --- a/doc/user/project/issues/closing_issues.md +++ b/doc/user/project/issues/closing_issues.md @@ -1,59 +1,5 @@ -# 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: - - - -## 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 - - - -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. - - - -## 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**. - - - -## 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). diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index c2916c79876..8eec29716c1 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -1,104 +1,5 @@ -# 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. - - - -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 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 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 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. - - - -## 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. - - - -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. - - - -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. - - - -## 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). diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index ff5b1f2ce50..93dc2a2e4ca 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -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).  @@ -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.  - -### 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). diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index b0b1cfcfdf7..e1e58e5ab24 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -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 diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md index 536a0de8974..e50259e0dcf 100644 --- a/doc/user/project/issues/deleting_issues.md +++ b/doc/user/project/issues/deleting_issues.md @@ -1,13 +1,5 @@ -# 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. - - - ->**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). diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 987c16dfab6..be577b3f24c 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -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.  -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.  ## 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.  @@ -36,14 +38,13 @@ Due dates also appear in your [todos list](../../../workflow/todos.md).  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 diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 4acbb4cc3f6..86c2f2f3959 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -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  -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  -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 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 + -- [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. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 2103f331aa2..9898cd6cf15 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -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. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md new file mode 100644 index 00000000000..663bacf4a45 --- /dev/null +++ b/doc/user/project/issues/managing_issues.md @@ -0,0 +1,204 @@ +# 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. + + + +### 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**: + +  + +- From an **opened issue** in your project, click **New Issue** to create a new + issue in the same project: + +  + +- 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: + +  + +- 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. + +  + +### 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. + + + +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. + + + +### 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. + + + +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. + + + +## Closing Issues + +When you decide that an issue is resolved, or no longer needed, you can close the issue +using the close button: + + + +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. + + + +### 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. + + + +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. + + diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md index 8aac2c01444..8331f865b83 100644 --- a/doc/user/project/issues/moving_issues.md +++ b/doc/user/project/issues/moving_issues.md @@ -1,35 +1,5 @@ -# 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. - - - -## 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). diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md index e90ecd88ec6..9cbac53ee41 100644 --- a/doc/user/project/issues/similar_issues.md +++ b/doc/user/project/issues/similar_issues.md @@ -1,16 +1,5 @@ -# 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. - - - -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). diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 447b338928c..169b10572b0 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -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) diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 13e4f2ce163..a81c9197ec1 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -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**_. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index ce9d23bf911..253e5374f52 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -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 diff --git a/doc/workflow/README.md b/doc/workflow/README.md index 40e2486ace5..45bd8c29a48 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -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) |