summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSean Packham (GitLab) <sean@seanpackham.com>2017-05-08 08:35:40 +0000
committerSean Packham (GitLab) <sean@seanpackham.com>2017-05-08 08:35:40 +0000
commit6386e42f06bb26746a9168a8c81ad03fa0356dbd (patch)
treeeb0c8c92e990f84ac2fc8785f962f282b6c03316
parent59c9ec5ce6ef5a59fe989a06f0b8fa94aaba31d7 (diff)
parentb13b22d04a6a2119541f7b5408eb6dedb896db17 (diff)
downloadgitlab-ce-6386e42f06bb26746a9168a8c81ad03fa0356dbd.tar.gz
Merge branch 'docs/new-topic-issues' into 'master'
New doc topic: issues Closes #27650 See merge request !11075
-rw-r--r--doc/README.md7
-rw-r--r--doc/gitlab-basics/README.md2
-rw-r--r--doc/gitlab-basics/create-issue.md30
-rw-r--r--doc/intro/README.md2
-rw-r--r--doc/user/project/issues/closing_issues.md59
-rw-r--r--doc/user/project/issues/create_new_issue.md38
-rw-r--r--doc/user/project/issues/crosslinking_issues.md63
-rw-r--r--doc/user/project/issues/due_dates.md6
-rwxr-xr-xdoc/user/project/issues/img/button_close_issue.pngbin0 -> 15508 bytes
-rw-r--r--doc/user/project/issues/img/close_issue_from_board.gifbin0 -> 109533 bytes
-rwxr-xr-xdoc/user/project/issues/img/closing_and_related_issues.pngbin0 -> 6395 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/confidential_issues_create.pngbin9659 -> 8185 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/confidential_issues_index_page.pngbin9949 -> 8349 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/confidential_issues_issue_page.pngbin16089 -> 14230 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/confidential_issues_search_guest.pngbin10014 -> 8593 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/confidential_issues_search_master.pngbin15332 -> 13228 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/confidential_issues_system_notes.pngbin3025 -> 2330 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/due_dates_create.pngbin7705 -> 6992 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/due_dates_edit_sidebar.pngbin2424 -> 1700 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/due_dates_issues_index_page.pngbin21402 -> 19302 bytes
-rwxr-xr-x[-rw-r--r--]doc/user/project/issues/img/due_dates_todos.pngbin5644 -> 4799 bytes
-rwxr-xr-xdoc/user/project/issues/img/issue_board.pngbin0 -> 58645 bytes
-rwxr-xr-xdoc/user/project/issues/img/issue_template.pngbin0 -> 28061 bytes
-rwxr-xr-xdoc/user/project/issues/img/issue_tracker.pngbin0 -> 37037 bytes
-rwxr-xr-xdoc/user/project/issues/img/issues_main_view.pngbin0 -> 48671 bytes
-rwxr-xr-xdoc/user/project/issues/img/issues_main_view_numbered.pngbin0 -> 73508 bytes
-rwxr-xr-xdoc/user/project/issues/img/mention_in_issue.pngbin0 -> 3738 bytes
-rwxr-xr-xdoc/user/project/issues/img/mention_in_merge_request.pngbin0 -> 3944 bytes
-rwxr-xr-xdoc/user/project/issues/img/merge_request_closes_issue.pngbin0 -> 19423 bytes
-rwxr-xr-xdoc/user/project/issues/img/new_issue.pngbin0 -> 31727 bytes
-rwxr-xr-xdoc/user/project/issues/img/new_issue_from_issue_board.pngbin0 -> 137175 bytes
-rwxr-xr-xdoc/user/project/issues/img/new_issue_from_open_issue.pngbin0 -> 20628 bytes
-rwxr-xr-xdoc/user/project/issues/img/new_issue_from_projects_dashboard.pngbin0 -> 29865 bytes
-rwxr-xr-xdoc/user/project/issues/img/new_issue_from_tracker_list.pngbin0 -> 24345 bytes
-rw-r--r--doc/user/project/issues/index.md100
-rw-r--r--doc/user/project/issues/issues_functionalities.md157
36 files changed, 426 insertions, 38 deletions
diff --git a/doc/README.md b/doc/README.md
index 4397465bd3d..7bab42bc135 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -60,11 +60,8 @@ Manage files and branches from the UI (user interface):
### Issues and Merge Requests (MRs)
- [Discussions](user/discussions/index.md) Threads, comments, and resolvable discussions in issues, commits, and merge requests.
-- Issues
- - [Create an issue](gitlab-basics/create-issue.md#how-to-create-an-issue-in-gitlab)
- - [Confidential Issues](user/project/issues/confidential_issues.md)
- - [Automatic issue closing](user/project/issues/automatic_issue_closing.md)
- - [Issue Boards](user/project/issue_board.md)
+- [Issues](user/project/issues/index.md)
+- [Issue Board](user/project/issue_board.md)
- [Issues and merge requests templates](user/project/description_templates.md): Create templates for submitting new issues and merge requests.
- [Labels](user/project/labels.md): Categorize your issues or merge requests based on descriptive titles.
- [Merge Requests](user/project/merge_requests/index.md)
diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md
index d7e3aa35bdd..12466437edc 100644
--- a/doc/gitlab-basics/README.md
+++ b/doc/gitlab-basics/README.md
@@ -11,5 +11,5 @@ Step-by-step guides on the basics of working with Git and GitLab.
- [Fork a project](fork-project.md)
- [Add a file](add-file.md)
- [Add an image](add-image.md)
-- [Create an issue](create-issue.md)
+- [Create an issue](../user/project/issues/create_new_issue.md)
- [Create a merge request](add-merge-request.md)
diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md
index 13e5a738c89..abb163dbf18 100644
--- a/doc/gitlab-basics/create-issue.md
+++ b/doc/gitlab-basics/create-issue.md
@@ -1,30 +1,2 @@
-# How to create an Issue in GitLab
-The issue tracker is a good place to add things that need to be improved or
-solved in a project.
-
----
-
-1. Go to the project where you'd like to create the issue and navigate to the
- **Issues** tab on top.
-
- ![Issues](img/project_navbar.png)
-
-1. Click on the **New issue** button on the right side of your screen.
-
- ![New issue](img/new_issue_button.png)
-
-1. At the very minimum, add a title and a description to your issue.
- You may assign it to a user, add a milestone or add labels (all optional).
-
- ![Issue title and description](img/new_issue_page.png)
-
-1. When ready, click on **Submit issue**.
-
----
-
-Your Issue will now be added to the issue tracker of the project you opened it
-at and will be ready to be reviewed. You can comment on it and mention the
-people involved. You can also link issues to the merge requests where the issues
-are solved. To do this, you can use an
-[issue closing pattern](../user/project/issues/automatic_issue_closing.md).
+This document was moved to [another location](../user/project/issues/index.md#new-issue).
diff --git a/doc/intro/README.md b/doc/intro/README.md
index d52b180a076..7485912d1a2 100644
--- a/doc/intro/README.md
+++ b/doc/intro/README.md
@@ -11,7 +11,7 @@ Create projects and groups.
Create issues, labels, milestones, cast your vote, and review issues.
-- [Create a new issue](../gitlab-basics/create-issue.md)
+- [Create a new issue](../user/project/issues/index.md#new-issue)
- [Assign labels to issues](../user/project/labels.md)
- [Use milestones as an overview of your project's tracker](../user/project/milestones/index.md)
- [Use voting to express your like/dislike to issues and merge requests](../workflow/award_emoji.md)
diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md
new file mode 100644
index 00000000000..dcfa5ff59b2
--- /dev/null
+++ b/doc/user/project/issues/closing_issues.md
@@ -0,0 +1,59 @@
+# Closing Issues
+
+Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
+
+## Directly
+
+Whenever you decide that's no longer need for that issue,
+close the issue using the close button:
+
+![close issue - button](img/button_close_issue.png)
+
+## Via Merge Request
+
+When a merge request resolves the discussion over an issue, you can
+make it close that issue(s) when merged.
+
+All you need is to use a [keyword](automatic_issue_closing.md)
+accompanying the issue number, add to the description of that MR.
+
+In this example, the keyword "closes" prefixing the issue number will create a relationship
+in such a way that the merge request will close the issue when merged.
+
+Mentioning various issues in the same line also works for this purpose:
+
+```md
+Closes #333, #444, #555 and #666
+```
+
+If the issue is in a different repository rather then the MR's,
+add the full URL for that issue(s):
+
+```md
+Closes #333, #444, and https://gitlab.com/<username>/<projectname>/issues/<xxx>
+```
+
+All the following keywords will produce the same behaviour:
+
+- Close, Closes, Closed, Closing, close, closes, closed, closing
+- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
+- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
+
+![merge request closing issue when merged](img/merge_request_closes_issue.png)
+
+If you use any other word before the issue number, the issue and the MR will
+link to each other, but the MR will NOT close the issue(s) when merged.
+
+![mention issues in MRs - closing and related](img/closing_and_related_issues.png)
+
+## From the Issue Board
+
+You can close an issue from [Issue Boards](../issue_board.md) by draging an issue card
+from its list and dropping into **Closed**.
+
+![close issue from the Issue Board](img/close_issue_from_board.gif)
+
+## Customizing the issue closing patern
+
+Alternatively, a GitLab **administrator** can
+[customize the issue closing patern](../../../administration/issue_closing_pattern.md).
diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md
new file mode 100644
index 00000000000..9af088374a1
--- /dev/null
+++ b/doc/user/project/issues/create_new_issue.md
@@ -0,0 +1,38 @@
+# Create a new Issue
+
+Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
+
+When you create a new issue, you'll be prompted to fill in
+the information illustrated on the image below.
+
+![New issue from the issues list](img/new_issue.png)
+
+Read through the [issues functionalities documentation](issues_functionalities.md#issues-functionalities)
+to understand these fields one by one.
+
+## New issue from the Issue Tracker
+
+Navigate to your **Project's Dashboard** > **Issues** > **New Issue** to create a new issue:
+
+![New issue from the issue list view](img/new_issue_from_tracker_list.png)
+
+## New issue from an opened issue
+
+From an **opened issue** in your project, click **New Issue** to create a new
+issue in the same project:
+
+![New issue from an open issue](img/new_issue_from_open_issue.png)
+
+## New issue from the project's dashboard
+
+From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown
+menu with a few options. Select **New Issue** to create an issue in that project:
+
+![New issue from a project's dashboard](img/new_issue_from_projects_dashboard.png)
+
+## New issue from the Issue Board
+
+From an Issue Board, create a new issue by clicking on the plus sign (**+**) on the top of a list.
+It opens a new issue for that project labeled after its respective list.
+
+![From the issue board](img/new_issue_from_issue_board.png)
diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md
new file mode 100644
index 00000000000..5cc7ea383ae
--- /dev/null
+++ b/doc/user/project/issues/crosslinking_issues.md
@@ -0,0 +1,63 @@
+# Crosslinking Issues
+
+Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
+
+## From Commit Messages
+
+Every time you mention an issue in your commit message, you're creating
+a relationship between the two stages of the development workflow: the
+issue itself and the first commit related to that issue.
+
+If the issue and the code you're committing are both in the same project,
+you simply add `#xxx` to the commit message, where `xxx` is the issue number.
+If they are not in the same project, you can add the full URL to the issue
+(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`).
+
+```shell
+git commit -m "this is my commit message. Ref #xxx"
+```
+
+or
+
+```shell
+git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/issues/<xxx>"
+```
+
+Of course, you can replace `gitlab.com` with the URL of your own GitLab instance.
+
+**Note:** Linking your first commit to your issue is going to be relevant
+for tracking your process far ahead with
+[GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/)).
+It will measure the time taken for planning the implementation of that issue,
+which is the time between creating an issue and making the first commit.
+
+## From Related Issues
+
+Mentioning related issues in merge requests and other issues is useful
+for your team members and collaborators to know that there are opened
+issues around that same idea.
+
+You do that as explained above, when
+[mentioning an issue from a commit message](#from-commit-messages).
+
+When mentioning the issue "A" in a issue "B", the issue "A" will also
+display a notification in its tracker. The same is valid for mentioning
+issues in merge requests.
+
+![issue mentioned in issue](img/mention_in_issue.png)
+
+## From Merge Requests
+
+Mentioning issues in merge request comments work exactly the same way
+they do for [related issues](#from-related-issues).
+
+When you mention an issue in a merge request description, you can either
+[close the issue as soon as the merge request is merged](closing_issues.md#via-merge-request),
+or simply link both issue and merge request as described in the
+[closing issues documentation](closing_issues.md#from-related-issues).
+
+![issue mentioned in MR](img/mention_in_merge_request.png)
+
+### Close an issue by merging a merge request
+
+To [close an issue when a merge request is merged](closing_issues.md#via-merge-request), use the [automatic issue closing patern](automatic_issue_closing.md).
diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md
index b516d47ffa3..e0c405353ce 100644
--- a/doc/user/project/issues/due_dates.md
+++ b/doc/user/project/issues/due_dates.md
@@ -2,6 +2,8 @@
> [Introduced][ce-3614] in GitLab 8.7.
+Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
+
Due dates can be used in issues to keep track of deadlines and make sure
features are shipped on time. Due dates require at least [Reporter permissions][permissions]
to be able to edit them. On the contrary, they can be seen by everybody.
@@ -22,8 +24,8 @@ Changes are saved immediately.
## Making use of due dates
-Issues that have a due date can be distinctively seen in the issues index page
-with a calendar icon next to them. Issues where the date is past due will have
+Issues that have a due date can be distinctively seen in the issue tracker
+displaying a date next to them. Issues where the date is overdue will have
the icon and the date colored red. You can sort issues by those that are
_Due soon_ or _Due later_ from the dropdown menu in the right.
diff --git a/doc/user/project/issues/img/button_close_issue.png b/doc/user/project/issues/img/button_close_issue.png
new file mode 100755
index 00000000000..8fb2e23f58a
--- /dev/null
+++ b/doc/user/project/issues/img/button_close_issue.png
Binary files differ
diff --git a/doc/user/project/issues/img/close_issue_from_board.gif b/doc/user/project/issues/img/close_issue_from_board.gif
new file mode 100644
index 00000000000..4814b42687b
--- /dev/null
+++ b/doc/user/project/issues/img/close_issue_from_board.gif
Binary files differ
diff --git a/doc/user/project/issues/img/closing_and_related_issues.png b/doc/user/project/issues/img/closing_and_related_issues.png
new file mode 100755
index 00000000000..c6543e85fdb
--- /dev/null
+++ b/doc/user/project/issues/img/closing_and_related_issues.png
Binary files differ
diff --git a/doc/user/project/issues/img/confidential_issues_create.png b/doc/user/project/issues/img/confidential_issues_create.png
index d259255599d..0a141eb39f8 100644..100755
--- a/doc/user/project/issues/img/confidential_issues_create.png
+++ b/doc/user/project/issues/img/confidential_issues_create.png
Binary files differ
diff --git a/doc/user/project/issues/img/confidential_issues_index_page.png b/doc/user/project/issues/img/confidential_issues_index_page.png
index 042461e2451..e4b492a2769 100644..100755
--- a/doc/user/project/issues/img/confidential_issues_index_page.png
+++ b/doc/user/project/issues/img/confidential_issues_index_page.png
Binary files differ
diff --git a/doc/user/project/issues/img/confidential_issues_issue_page.png b/doc/user/project/issues/img/confidential_issues_issue_page.png
index b3568e9303a..f04ec8ff32b 100644..100755
--- a/doc/user/project/issues/img/confidential_issues_issue_page.png
+++ b/doc/user/project/issues/img/confidential_issues_issue_page.png
Binary files differ
diff --git a/doc/user/project/issues/img/confidential_issues_search_guest.png b/doc/user/project/issues/img/confidential_issues_search_guest.png
index b85de90b4d5..dc1b4ba8ad7 100644..100755
--- a/doc/user/project/issues/img/confidential_issues_search_guest.png
+++ b/doc/user/project/issues/img/confidential_issues_search_guest.png
Binary files differ
diff --git a/doc/user/project/issues/img/confidential_issues_search_master.png b/doc/user/project/issues/img/confidential_issues_search_master.png
index bf2b9428875..fc01f4da9db 100644..100755
--- a/doc/user/project/issues/img/confidential_issues_search_master.png
+++ b/doc/user/project/issues/img/confidential_issues_search_master.png
Binary files differ
diff --git a/doc/user/project/issues/img/confidential_issues_system_notes.png b/doc/user/project/issues/img/confidential_issues_system_notes.png
index 4005f9350f7..82e0dd8e85e 100644..100755
--- a/doc/user/project/issues/img/confidential_issues_system_notes.png
+++ b/doc/user/project/issues/img/confidential_issues_system_notes.png
Binary files differ
diff --git a/doc/user/project/issues/img/due_dates_create.png b/doc/user/project/issues/img/due_dates_create.png
index d2fe1172bab..ece35d44213 100644..100755
--- a/doc/user/project/issues/img/due_dates_create.png
+++ b/doc/user/project/issues/img/due_dates_create.png
Binary files differ
diff --git a/doc/user/project/issues/img/due_dates_edit_sidebar.png b/doc/user/project/issues/img/due_dates_edit_sidebar.png
index 6b37150e7db..d1c7d1eb7e9 100644..100755
--- a/doc/user/project/issues/img/due_dates_edit_sidebar.png
+++ b/doc/user/project/issues/img/due_dates_edit_sidebar.png
Binary files differ
diff --git a/doc/user/project/issues/img/due_dates_issues_index_page.png b/doc/user/project/issues/img/due_dates_issues_index_page.png
index defcd5eca39..94679436b32 100644..100755
--- a/doc/user/project/issues/img/due_dates_issues_index_page.png
+++ b/doc/user/project/issues/img/due_dates_issues_index_page.png
Binary files differ
diff --git a/doc/user/project/issues/img/due_dates_todos.png b/doc/user/project/issues/img/due_dates_todos.png
index 92c9fd4021b..4c124c97f67 100644..100755
--- a/doc/user/project/issues/img/due_dates_todos.png
+++ b/doc/user/project/issues/img/due_dates_todos.png
Binary files differ
diff --git a/doc/user/project/issues/img/issue_board.png b/doc/user/project/issues/img/issue_board.png
new file mode 100755
index 00000000000..1759b28a9ef
--- /dev/null
+++ b/doc/user/project/issues/img/issue_board.png
Binary files differ
diff --git a/doc/user/project/issues/img/issue_template.png b/doc/user/project/issues/img/issue_template.png
new file mode 100755
index 00000000000..c63229a4af2
--- /dev/null
+++ b/doc/user/project/issues/img/issue_template.png
Binary files differ
diff --git a/doc/user/project/issues/img/issue_tracker.png b/doc/user/project/issues/img/issue_tracker.png
new file mode 100755
index 00000000000..ab25cb64d13
--- /dev/null
+++ b/doc/user/project/issues/img/issue_tracker.png
Binary files differ
diff --git a/doc/user/project/issues/img/issues_main_view.png b/doc/user/project/issues/img/issues_main_view.png
new file mode 100755
index 00000000000..e9a94a3aab0
--- /dev/null
+++ b/doc/user/project/issues/img/issues_main_view.png
Binary files differ
diff --git a/doc/user/project/issues/img/issues_main_view_numbered.png b/doc/user/project/issues/img/issues_main_view_numbered.png
new file mode 100755
index 00000000000..9cff61d7041
--- /dev/null
+++ b/doc/user/project/issues/img/issues_main_view_numbered.png
Binary files differ
diff --git a/doc/user/project/issues/img/mention_in_issue.png b/doc/user/project/issues/img/mention_in_issue.png
new file mode 100755
index 00000000000..c762a812138
--- /dev/null
+++ b/doc/user/project/issues/img/mention_in_issue.png
Binary files differ
diff --git a/doc/user/project/issues/img/mention_in_merge_request.png b/doc/user/project/issues/img/mention_in_merge_request.png
new file mode 100755
index 00000000000..681e086d6e0
--- /dev/null
+++ b/doc/user/project/issues/img/mention_in_merge_request.png
Binary files differ
diff --git a/doc/user/project/issues/img/merge_request_closes_issue.png b/doc/user/project/issues/img/merge_request_closes_issue.png
new file mode 100755
index 00000000000..6fd27738843
--- /dev/null
+++ b/doc/user/project/issues/img/merge_request_closes_issue.png
Binary files differ
diff --git a/doc/user/project/issues/img/new_issue.png b/doc/user/project/issues/img/new_issue.png
new file mode 100755
index 00000000000..e72ac49d6b9
--- /dev/null
+++ b/doc/user/project/issues/img/new_issue.png
Binary files differ
diff --git a/doc/user/project/issues/img/new_issue_from_issue_board.png b/doc/user/project/issues/img/new_issue_from_issue_board.png
new file mode 100755
index 00000000000..9c2b3ff50fa
--- /dev/null
+++ b/doc/user/project/issues/img/new_issue_from_issue_board.png
Binary files differ
diff --git a/doc/user/project/issues/img/new_issue_from_open_issue.png b/doc/user/project/issues/img/new_issue_from_open_issue.png
new file mode 100755
index 00000000000..2aed5372830
--- /dev/null
+++ b/doc/user/project/issues/img/new_issue_from_open_issue.png
Binary files differ
diff --git a/doc/user/project/issues/img/new_issue_from_projects_dashboard.png b/doc/user/project/issues/img/new_issue_from_projects_dashboard.png
new file mode 100755
index 00000000000..cddf36b7457
--- /dev/null
+++ b/doc/user/project/issues/img/new_issue_from_projects_dashboard.png
Binary files differ
diff --git a/doc/user/project/issues/img/new_issue_from_tracker_list.png b/doc/user/project/issues/img/new_issue_from_tracker_list.png
new file mode 100755
index 00000000000..7e5413f0b7d
--- /dev/null
+++ b/doc/user/project/issues/img/new_issue_from_tracker_list.png
Binary files differ
diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md
new file mode 100644
index 00000000000..c726da17259
--- /dev/null
+++ b/doc/user/project/issues/index.md
@@ -0,0 +1,100 @@
+# GitLab Issues Documentation
+
+The GitLab Issue Tracker is an advanced and complete tool
+for tracking the evolution of a new idea or the process
+of solving a problem.
+
+It allows you, your team, and your collaborators to share
+and discuss proposals, before and while implementing them.
+
+Issues and the GitLab Issue Tracker are available in all
+[GitLab Products](https://about.gitlab.com/products/) as
+part of the [GitLab Workflow](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/).
+
+## Use-Cases
+
+Issues can have endless applications. Just to exemplify, these are
+some cases for which creating issues are most used:
+
+- Discussing the implementation of a new idea
+- Submitting feature proposals
+- Asking questions
+- Reporting bugs and malfunction
+- Obtaining support
+- Elaborating new code implementations
+
+See also the blog post [Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/).
+
+## Issue Tracker
+
+The issue tracker is the collection of opened and closed issues created in a project.
+
+![Issue tracker](img/issue_tracker.png)
+
+Find the issue tracker by navigating to your **Project's Dashboard** > **Issues**.
+
+## GitLab Issues Functionalities
+
+The image bellow illustrates how an issue looks like:
+
+![Issue view](img/issues_main_view.png)
+
+Learn more about it on the [GitLab Issues Functionalities documentation](issues_functionalities.md).
+
+## New Issue
+
+Read through the [documentation on creating issues](create_new_issue.md).
+
+## Closing issues
+
+Read through the distinct ways to [close issues](closing_issues.md) on GitLab.
+
+## Search for an issue
+
+Learn how to [find an issue](../../search/index.md) by searching for and filtering them.
+
+## Advanced features
+
+### Confidential Issues
+
+Whenever you want to keep the discussion presented in a
+issue within your team only, you can make that
+[issue confidential](confidential_issues.md). Even if your project
+is public, that issue will be preserved. The browser will
+respond with a 404 error whenever someone who is not a project
+member with at least [Reporter level](../../permissions.md#project) tries to
+access that issue's URL.
+
+Learn more about them on the [confidential issues documentation](confidential_issues.md).
+
+### Issue templates
+
+Create templates for every new issue. They will be available from
+the dropdown menu **Choose a template** when you create a new issue:
+
+![issue template](img/issue_template.png)
+
+Learn more about them on the [issue templates documentation](../../project/description_templates.md#creating-issue-templates).
+
+### Crosslinking issues
+
+Learn more about [crosslinking](crosslinking_issues.md) issues and merge requests.
+
+### GitLab Issue Board
+
+The [GitLab Issue Board](https://about.gitlab.com/features/issueboard/) is a way to
+enhance your workflow by organizing and prioritizing issues in GitLab.
+
+![Issue board](img/issue_board.png)
+
+Find GitLab Issue Boards by navigating to your **Project's Dashboard** > **Issues** > **Board**.
+
+Read through the documentation for [Issue Boards](../issue_board.md)
+to find out more about this feature.
+
+[Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-boards)
+are available only in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/).
+
+### Issue's API
+
+Read through the [API documentation](../../../api/issues.md).
diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md
new file mode 100644
index 00000000000..1efd07a058b
--- /dev/null
+++ b/doc/user/project/issues/issues_functionalities.md
@@ -0,0 +1,157 @@
+# GitLab Issues Functionalities
+
+Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
+
+## Issues Functionalities
+
+The image bellow illustrates how an issue looks like:
+
+![Issue view](img/issues_main_view_numbered.png)
+
+You can find all the information on that issue on one screen.
+
+### Issue screen
+
+An issue starts with its status (open or closed), followed by its author,
+and includes many other functionalities, numbered on the image above to
+explain what they mean, one by one.
+
+#### 1. New Issue, close issue, edit
+
+- New issue: create a new issue in the same project
+- Close issue: close this issue
+- Edit: edit the same fields available when you create an issue.
+
+#### 2. Todos
+
+- Add todo: add that issue to your [GitLab Todo](../../../workflow/todos.html) list
+- Mark done: mark that issue as done (reflects on the Todo list)
+
+#### 3. Assignee
+
+Whenever someone starts to work on an issue, it can be assigned
+to that person. The assignee can be changed as much as needed.
+The idea is that the assignee is responsible for that issue until
+it's reassigned to someone else to take it from there.
+
+> **Tip:**
+if a user is not member of that project, it can only be
+assigned to them if they created the issue themselves.
+
+#### 4. Milestone
+
+- Select a [milestone](../milestones/index.md) to attribute that issue to.
+
+#### 5. Time Tracking (EES/EEP)
+
+This feature is available only in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/).
+
+- Estimate time: add an estimate time in which the issue will be implemented
+- Spend: add the time spent on the implementation of that issue
+
+> **Note:**
+both estimate and spend times are set via [GitLab Slash Commands](../slash_commands.md).
+
+Learn more on the [Time Tracking documentation](https://docs.gitlab.com/ee/workflow/time_tracking.html).
+
+#### 6. Due date
+
+When you work on a tight schedule, and it's important to
+have a way to setup a deadline for implementations and for solving
+problems. This can be facilitated by the [due date](due_dates.md)). Due dates
+can be changed as many times as needed.
+
+#### 7. Labels
+
+Categorize issues by giving them [labels](../labels.md). They help to
+organize team's workflows, once they enable you to work with the
+[GitLab Issue Board](index.md#gitlab-issue-board).
+
+Group Labels, which allow you to use the same labels per
+group of projects, can be also given to issues. They work exactly the same,
+but they are immediately available to all projects in the group.
+
+> **Tip:**
+if the label doesn't exist yet, when you click **Edit**, it opens a dropdown menu from which you can select **Create new label**.
+
+#### 8. Weight (EES/EEP)
+
+Issue Weights are only available in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/).
+
+- Attribute a weight (in a 0 to 9 range) to that issue. Easy to complete
+should weight 1 and very hard to complete should weight 9.
+
+Learn more on the [Issue Weight documentation](https://docs.gitlab.com/ee/workflow/issue_weight.html).
+
+#### 9. Participants
+
+- People involved in that issue (mentioned in the description or in the [discussion](../../discussions/index.md)).
+
+#### 10. Notifications
+
+- Subscribe: if you are not a participant of the discussion on that issue, but
+want to receive notifications on each new input, subscribe to it.
+- Unsubscribe: if you are receiving notifications on that issue but no
+longer want to receive them, unsubscribe to it.
+
+Read more on the [notifications documentation](../../../workflow/notifications.md#issue-merge-request-events).
+
+#### 11. Reference
+
+- A quick "copy to clipboard" button to that issue's reference, `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar`
+is the `project-name`, and `xxx` is the issue number.
+
+#### 12. Title and description
+
+- Title: a plain text title describing the issue's subject.
+- Description: a text field which fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
+
+#### 13. @mentions
+
+- Mentions: you can either `@mention` a user or a group present in your
+GitLab instance and they will be notified via todos and email, unless that
+person has disabled all notifications in their profile settings.
+
+To change your [notification settings](../../../workflow/notifications.md) navigate to
+**Profile Settings** > **Notifications** > **Global notification level**
+and choose your preferences from the dropdown menu.
+
+> **Tip:**
+Avoid mentioning `@all` in issues and merge requests,
+as it sends an email notification
+to all the members of that project's group, which can be
+interpreted as spam.
+
+#### 14. Related Merge Requests
+
+- Any merge requests mentioned in that issue's description
+or in the issue thread.
+
+#### 15. Award emoji
+
+- Award an emoji to that issue.
+
+> **Tip:**
+Posting "+1" as comments in threads spam all
+participants of that issue. Awarding an emoji is a way to let them
+know you like it without spamming them.
+
+#### 16. Thread
+
+- Comments: collaborate to that issue by posting comments in its thread.
+These text fields also fully support
+[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
+
+#### 17. Comment, start a discusion, or comment and close
+
+Once you wrote your comment, you can either:
+
+- Click "Comment" and your comment will be published.
+- Click "Start discussion": start a thread within that issue's thread to discuss specific points.
+- Click "Comment and close issue": post your comment and close that issue in one click.
+
+#### 18. New branch
+
+- [New branch](../repository/web_editor.md#create-a-new-branch-from-an-issue):
+create a new branch, followed by a new merge request which will automatically close that
+issue as soon as that merge request is merged.