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

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
19dc1105 · Evan Read · c55bbef9 · 4efc8574 · 19dc1105 · 19dc1105
Commit 19dc1105 authored Jul 04, 2019 by Evan Read
26 changed files
--- 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.                                                                                                       |

--- 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):

--- 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

--- a/doc/administration/issue_closing_pattern.md
+++ b/doc/administration/issue_closing_pattern.md
-# 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
--- a/doc/customization/issue_closing.md
+++ b/doc/customization/issue_closing.md
 ---
-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).
--- 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).

--- 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).

--- a/doc/gitlab-basics/create-issue.md
+++ b/doc/gitlab-basics/create-issue.md
 ---
-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).
--- 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)

--- 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
--- a/doc/user/project/issues/automatic_issue_closing.md
+++ b/doc/user/project/issues/automatic_issue_closing.md
-# 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`).
 ---
+redirect_to: 'managing_issues.md#closing-issues-automatically'
-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
 ---
-For example the following commit message:
+This document was moved to [another location](managing_issues.md#closing-issues-automatically).
-```
-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
--- a/doc/user/project/issues/closing_issues.md
+++ b/doc/user/project/issues/closing_issues.md
-# Closing Issues
+---
+redirect_to: 'managing_issues.md#closing-issues'
+---
-Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
+This document was moved to [another location](managing_issues.md#closing-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).
--- a/doc/user/project/issues/create_new_issue.md
+++ b/doc/user/project/issues/create_new_issue.md
-# 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.
+This document was moved to [another location](managing_issues.md#create-a-new-issue).
-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`
--- 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
+NOTE: **Note:** Linking your first commit to your issue is going to be relevant
-for tracking your process far ahead with
+for tracking your process with [GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/).
-[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
+You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages).
-[mentioning an issue from a commit message](#from-commit-messages).
-When mentioning the issue "A" in issue "B", the issue "A" will also
+When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification
-display a notification in its tracker. The same is valid for mentioning
+in its tracker. That is, you only need to mention the relationship once for it to
-issues in merge requests.
+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).
--- 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
+The double-quote (`"`) character is used to quote fields, enabling the use of the column
-a double-quote (`"`) within a quoted field, use two double-quote characters in succession, i.e. `""`.
+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
+After the header row, succeeding rows must follow the same column order. The issue
-description is optional.
+title is required while the description is optional.
 ### File size

--- a/doc/user/project/issues/deleting_issues.md
+++ b/doc/user/project/issues/deleting_issues.md
-# Deleting Issues
+---
+redirect_to: 'managing_issues.md#deleting-issues'
+---
-> [Introduced][ce-2982] in GitLab 8.6
+This document was moved to [another location](managing_issues.md#deleting-issues).
-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
--- 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
+Due dates can be used in issues to keep track of deadlines and make sure features are
-features are shipped on time. Due dates require at least [Reporter permissions](../../permissions.md#project-members-permissions)
+shipped on time. Users must have at least [Reporter permissions](../../permissions.md)
-to be able to edit them. On the contrary, they can be seen by everybody.
+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
+When creating or editing an issue, you can click in the **due date** field and a calendar
-a calendar will appear to help you choose the date you want. To remove it,
+will appear to help you choose the date you want. To remove the date, select the date
-select the date text and delete it.
+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
+You can also set a due date via the issue sidebar. Expand the
-sidebar and select **Edit** to pick a due date or remove the existing one.
+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
+of the issue. Like the due date, the "day before the due date" is determined by the
-server's timezone.
+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
+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 **Subscribe to calendar** button on the following pages:
- on the **Assigned Issues** page that is linked on the right-hand side of the
+- on the **Assigned Issues** page that is linked on the right-hand side of the GitLab header
-  GitLab header
 - on the **Project Issues** page
 - on the **Group Issues** page
--- 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.
+Issues can allow you, your team, and your collaborators to share and discuss proposals
-However, they can be used for a variety of other purposes, customized to your needs and workflow.
+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).
+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).
-For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page.
 ### 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.
+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
-For more information, see the [Issue Boards](../issue_board.md) page.
+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.
+[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
-For more information, see the [Epics](../../group/epics/index.md) page.
+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.
+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
-For more information, see [Related Issues](related_issues.md).
+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)
+To prevent duplication of issues for the same topic, GitLab searches for similar issues
- [Create an issue from a template](../../project/description_templates.md#using-the-templates)
+when new issues are being created.
- [Close an issue](closing_issues.md)
- [Move an issue](moving_issues.md)
+When typing in the title in the new issue form, GitLab searches titles and descriptions
- [Delete an issue](deleting_issues.md)
+across all issues the user has access to in the current project. Up 5 similar issues,
- [Create a merge request from an issue](issue_data_and_actions.md#22-create-merge-request)
+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,
+- Configure an [external issue tracker](../../../integration/external-issue-tracker.md)
-  or Bugzilla.
+  such as Jira, Redmine, or Bugzilla.
--- 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.

--- a/doc/user/project/issues/managing_issues.md
+++ b/doc/user/project/issues/managing_issues.md
+# 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)
--- a/doc/user/project/issues/moving_issues.md
+++ b/doc/user/project/issues/moving_issues.md
-# Moving Issues
+---
+redirect_to: 'managing_issues.md#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
-```
+This document was moved to [another location](managing_issues.md#moving-issues).
--- a/doc/user/project/issues/similar_issues.md
+++ b/doc/user/project/issues/similar_issues.md
-# Similar issues
+---
+redirect_to: 'index.md#similar-issues'
+---
-> [Introduced][ce-22866] in GitLab 11.6.
+This document was moved to [another location](index.md#similar-issues).
-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
--- 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)

--- 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**_.

--- 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
--- 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)