Add latest changes from gitlab-org/gitlab@master

19 files changed, 387 insertions, 15 deletions

diff --git a/doc/user/img/todos_add_todo_sidebar.png b/doc/user/img/todos_add_todo_sidebar.png
new file mode 100644
index 00000000000..aefec7a2d9c
--- /dev/null
+++ b/doc/user/img/todos_add_todo_sidebar.png
diff --git a/doc/user/img/todos_icon.png b/doc/user/img/todos_icon.png
new file mode 100644
index 00000000000..9fee4337a75
--- /dev/null
+++ b/doc/user/img/todos_icon.png
diff --git a/doc/user/img/todos_index.png b/doc/user/img/todos_index.png
new file mode 100644
index 00000000000..99c1575d157
--- /dev/null
+++ b/doc/user/img/todos_index.png
diff --git a/doc/user/img/todos_mark_done_sidebar.png b/doc/user/img/todos_mark_done_sidebar.png
new file mode 100644
index 00000000000..2badd880b40
--- /dev/null
+++ b/doc/user/img/todos_mark_done_sidebar.png
diff --git a/doc/user/img/todos_todo_list_item.png b/doc/user/img/todos_todo_list_item.png
new file mode 100644
index 00000000000..91bbf9e5373
--- /dev/null
+++ b/doc/user/img/todos_todo_list_item.png
diff --git a/doc/user/index.md b/doc/user/index.md
index 811691dfb15..0c6fb0aa5e2 100644
--- a/doc/user/index.md
+++ b/doc/user/index.md
@@ -135,7 +135,7 @@ supported.
 
 ## Todos
 
-Never forget to reply to your collaborators. [GitLab Todos](../workflow/todos.md)
+Never forget to reply to your collaborators. [GitLab Todos](todos.md)
 are a tool for working faster and more effectively with your team,
 by listing all user or group mentions, as well as issues and merge
 requests you're assigned to.
@@ -150,6 +150,11 @@ requests you're assigned to.
 you have quick access to. You can also gather feedback on them through
 [Discussions](#Discussions).
 
+## Keyboard shortcuts
+
+There are many [keyboard shortcuts](shortcuts.md) in GitLab to help you navigate between
+pages and accomplish tasks faster.
+
 ## Integrations
 
 [Integrate GitLab](../integration/README.md) with your preferred tool,
diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md
index 82a6d2b3703..9b43f6317d0 100644
--- a/doc/user/profile/preferences.md
+++ b/doc/user/profile/preferences.md
@@ -82,7 +82,7 @@ You have 8 options here that you can use for your default dashboard view:
 - Your projects' activity
 - Starred projects' activity
 - Your groups
-- Your [Todos](../../workflow/todos.md)
+- Your [Todos](../todos.md)
 - Assigned Issues
 - Assigned Merge Requests
 - Operations Dashboard **(PREMIUM)**
diff --git a/doc/user/project/img/time_tracking_example_v12_2.png b/doc/user/project/img/time_tracking_example_v12_2.png
new file mode 100644
index 00000000000..31d8c490ed1
--- /dev/null
+++ b/doc/user/project/img/time_tracking_example_v12_2.png
diff --git a/doc/user/project/img/time_tracking_sidebar_v8_16.png b/doc/user/project/img/time_tracking_sidebar_v8_16.png
new file mode 100644
index 00000000000..22124afed6f
--- /dev/null
+++ b/doc/user/project/img/time_tracking_sidebar_v8_16.png
diff --git a/doc/user/project/index.md b/doc/user/project/index.md
index 516a58bc671..c173d3d3e11 100644
--- a/doc/user/project/index.md
+++ b/doc/user/project/index.md
@@ -45,7 +45,7 @@ When you create a project in GitLab, you'll have access to a large number of
   - [Review Apps](../../ci/review_apps/index.md): Live preview the results
   of the changes proposed in a merge request in a per-branch basis
 - [Labels](labels.md): Organize issues and merge requests by labels
-- [Time Tracking](../../workflow/time_tracking.md): Track estimate time
+- [Time Tracking](time_tracking.md): Track estimate time
   and time spent on
   the conclusion of an issue or merge request
 - [Milestones](milestones/index.md): Work towards a target date
diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md
index fb7fdde7b94..b97bcd47f61 100644
--- a/doc/user/project/issues/csv_export.md
+++ b/doc/user/project/issues/csv_export.md
@@ -67,8 +67,8 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot
 | Milestone | Title of the issue milestone |
 | Weight | Issue weight |
 | Labels | Title of any labels joined with a `,` |
-| Time Estimate | [Time estimate](../../../workflow/time_tracking.md#estimates) in seconds |
-| Time Spent | [Time spent](../../../workflow/time_tracking.md#time-spent) in seconds |
+| Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds |
+| Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds |
 
 ## Limitations
 
diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md
index 169da7049a6..86c80e95699 100644
--- a/doc/user/project/issues/design_management.md
+++ b/doc/user/project/issues/design_management.md
@@ -38,8 +38,6 @@ to be enabled:
 - Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff` or `ico`.
   The [`svg` extension is not yet supported](https://gitlab.com/gitlab-org/gitlab/issues/12771).
 - Design uploads are limited to 10 files at a time.
-- Design Management is
-  [not yet supported in the project export](https://gitlab.com/gitlab-org/gitlab/issues/11090).
 - Design Management data
   [isn't deleted when a project is destroyed](https://gitlab.com/gitlab-org/gitlab/issues/13429) yet.
 - Design Management data [won't be moved](https://gitlab.com/gitlab-org/gitlab/issues/13426)
diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md
index 240859651e2..b19d5dc1650 100644
--- a/doc/user/project/issues/due_dates.md
+++ b/doc/user/project/issues/due_dates.md
@@ -33,7 +33,7 @@ the icon and the date colored red. You can sort issues by those that are
 
 ![Issues with due dates in the issues index page](img/due_dates_issues_index_page.png)
 
-Due dates also appear in your [todos list](../../../workflow/todos.md).
+Due dates also appear in your [todos list](../../todos.md).
 
 ![Issues with due dates in the todos](img/due_dates_todos.png)
 
diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md
index 6dee1351aa7..f4e9434ef1a 100644
--- a/doc/user/project/issues/issue_data_and_actions.md
+++ b/doc/user/project/issues/issue_data_and_actions.md
@@ -41,7 +41,7 @@ after it is closed.
 
 #### 2. To Do
 
-You can add issues to and remove issues from your [GitLab To-Do List](../../../workflow/todos.md).
+You can add issues to and remove issues from your [GitLab To-Do List](../../todos.md).
 
 The button to do this has a different label depending on whether the issue is already on your To-Do List or not. If the issue is:
 
@@ -83,9 +83,9 @@ Select a [milestone](../milestones/index.md) to attribute that issue to.
 
 #### 6. Time Tracking
 
-Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../../../workflow/time_tracking.md).
-You can add an [estimate of the time it will take](../../../workflow/time_tracking.md#estimates)
-to resolve the issue, and also add [the time spent](../../../workflow/time_tracking.md#time-spent)
+Use [GitLab Quick Actions](../quick_actions.md) to [track estimates and time spent on issues](../time_tracking.md).
+You can add an [estimate of the time it will take](../time_tracking.md#estimates)
+to resolve the issue, and also add [the time spent](../time_tracking.md#time-spent)
 on the resolution of the issue.
 
 #### 7. Due date
diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index 00879aae931..97bd5dc3bc6 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -27,7 +27,7 @@ With GitLab merge requests, you can:
 - 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)
-- Add a time estimation and the time spent with that merge request with [Time Tracking](../../../workflow/time_tracking.md#time-tracking)
+- Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking)
 - [Resolve merge conflicts from the UI](#resolve-conflicts)
 - Enable [fast-forward merge requests](#fast-forward-merge-requests)
 - Enable [semi-linear history merge requests](#semi-linear-history-merge-requests) as another security layer to guarantee the pipeline is passing in the target branch
diff --git a/doc/user/project/time_tracking.md b/doc/user/project/time_tracking.md
new file mode 100644
index 00000000000..9cdee0f2b5a
--- /dev/null
+++ b/doc/user/project/time_tracking.md
@@ -0,0 +1,92 @@
+---
+type: reference
+disqus_identifier: 'https://docs.gitlab.com/ee/workflow/time_tracking.html'
+---
+
+# Time Tracking
+
+> Introduced in GitLab 8.14.
+
+Time Tracking allows you to track estimates and time spent on issues and merge
+requests within GitLab.
+
+## Overview
+
+Time Tracking allows you to:
+
+- Record the time spent working on an issue or a merge request.
+- Add an estimate of the amount of time needed to complete an issue or a merge
+  request.
+
+You don't have to indicate an estimate to enter the time spent, and vice versa.
+
+Data about time tracking is shown on the issue/merge request sidebar, as shown
+below.
+
+![Time tracking in the sidebar](img/time_tracking_sidebar_v8_16.png)
+
+## How to enter data
+
+Time Tracking uses two [quick actions](quick_actions.md)
+that GitLab introduced with this new feature: `/spend` and `/estimate`.
+
+Quick actions can be used in the body of an issue or a merge request, but also
+in a comment in both an issue or a merge request.
+
+Below is an example of how you can use those new quick actions inside a comment.
+
+![Time tracking example in a comment](img/time_tracking_example_v12_2.png)
+
+Adding time entries (time spent or estimates) is limited to project members.
+
+### Estimates
+
+To enter an estimate, write `/estimate`, followed by the time. For example, if
+you need to enter an estimate of 3 days, 5 hours and 10 minutes, you would write
+`/estimate 3d 5h 10m`. Time units that we support are listed at the bottom of
+this help page.
+
+Every time you enter a new time estimate, any previous time estimates will be
+overridden by this new value. There should only be one valid estimate in an
+issue or a merge request.
+
+To remove an estimation entirely, use `/remove_estimate`.
+
+### Time spent
+
+To enter a time spent, use `/spend 3d 5h 10m`.
+
+Every new time spent entry will be added to the current total time spent for the
+issue or the merge request.
+
+You can remove time by entering a negative amount: `/spend -3d` will remove 3
+days from the total time spent. You can't go below 0 minutes of time spent,
+so GitLab will automatically reset the time spent if you remove a larger amount
+of time compared to the time that was entered already.
+
+To remove all the time spent at once, use `/remove_time_spent`.
+
+## Configuration
+
+The following time units are available:
+
+- Months (mo)
+- Weeks (w)
+- Days (d)
+- Hours (h)
+- Minutes (m)
+
+Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h.
+
+### Limit displayed units to hours **(CORE ONLY)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/29469/) in GitLab 12.1.
+
+In GitLab self-managed instances, the display of time units can be limited to
+hours through the option in **Admin Area > Settings > Preferences** under **Localization**.
+
+With this option enabled, `75h` is displayed instead of `1w 4d 3h`.
+
+## Other interesting links
+
+- [Time Tracking landing page in the GitLab handbook](https://about.gitlab.com/solutions/time-tracking/)
diff --git a/doc/user/search/index.md b/doc/user/search/index.md
index 8d7b4a429aa..33f920440ac 100644
--- a/doc/user/search/index.md
+++ b/doc/user/search/index.md
@@ -99,8 +99,8 @@ quickly access issues and merge requests created or assigned to you within that
 
 ## To-Do List
 
-Your [To-Do List](../../workflow/todos.md#gitlab-to-do-list) can be searched by "to do" and "done".
-You can [filter](../../workflow/todos.md#filtering-your-to-do-list) them per project,
+Your [To-Do List](../todos.md#gitlab-to-do-list) can be searched by "to do" and "done".
+You can [filter](../todos.md#filtering-your-to-do-list) them per project,
 author, type, and action. Also, you can sort them by
 [**Label priority**](../../user/project/labels.md#label-priority),
 **Last created** and **Oldest created**.
diff --git a/doc/user/shortcuts.md b/doc/user/shortcuts.md
new file mode 100644
index 00000000000..54e7938d8f7
--- /dev/null
+++ b/doc/user/shortcuts.md
@@ -0,0 +1,135 @@
+---
+type: reference
+disqus_identifier: 'https://docs.gitlab.com/ee/workflow/shortcuts.html'
+---
+
+# GitLab keyboard shortcuts
+
+GitLab has many useful keyboard shortcuts to make it easier to access different features.
+You can see the quick reference sheet within GitLab itself with <kbd>Shift</kbd> + <kbd>?</kbd>.
+
+The [Global Shortcuts](#global-shortcuts) work from any area of GitLab, but you must
+be in specific pages for the other shortcuts to be available, as explained in each
+section below.
+
+## Global Shortcuts
+
+These shortcuts are available in most areas of GitLab
+
+| Keyboard Shortcut               | Description |
+| ------------------------------- | ----------- |
+| <kbd>?</kbd>                    | Show/hide shortcut reference sheet. |
+| <kbd>Shift</kbd> + <kbd>p</kbd> | Go to your Projects page. |
+| <kbd>Shift</kbd> + <kbd>g</kbd> | Go to your Groups page. |
+| <kbd>Shift</kbd> + <kbd>a</kbd> | Go to your Activity page. |
+| <kbd>Shift</kbd> + <kbd>l</kbd> | Go to your Milestones page. |
+| <kbd>Shift</kbd> + <kbd>s</kbd> | Go to your Snippets page. |
+| <kbd>s</kbd>                    | Put cursor in the issues/merge requests search. |
+| <kbd>Shift</kbd> + <kbd>i</kbd> | Go to your Issues page. |
+| <kbd>Shift</kbd> + <kbd>m</kbd> | Go to your Merge requests page.|
+| <kbd>Shift</kbd> + <kbd>t</kbd> | Go to your To-Do List page. |
+| <kbd>p</kbd> + <kbd>b</kbd>     | Show/hide the Performance Bar. |
+
+Additionally, the following shortcuts are available when editing text in text fields,
+for example comments, replies, or issue and merge request descriptions:
+
+| Keyboard Shortcut                                                      | Description |
+| ---------------------------------------------------------------------- | ----------- |
+| <kbd>↑</kbd>                                                           | Edit your last comment. You must be in a blank text field below a thread, and you must already have at least one comment in the thread. |
+| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>p</kbd> | Toggle Markdown preview, when editing text in a text field that has **Write** and **Preview** tabs at the top. |
+
+## Project
+
+These shortcuts are available from any page within a project. You must type them
+relatively quickly to work, and they will take you to another page in the project.
+
+| Keyboard Shortcut           | Description |
+| --------------------------- | ----------- |
+| <kbd>g</kbd> + <kbd>p</kbd> | Go to the project home page (**Project > Details**). |
+| <kbd>g</kbd> + <kbd>v</kbd> | Go to the project activity feed (**Project > Activity**). |
+| <kbd>g</kbd> + <kbd>r</kbd> | Go to the project releases list (**Project > Releases**). |
+| <kbd>g</kbd> + <kbd>f</kbd> | Go to the [project files](#project-files) list (**Repository > Files**). |
+| <kbd>t</kbd>                | Go to the project file search page. (**Repository > Files**, click **Find Files**). |
+| <kbd>g</kbd> + <kbd>c</kbd> | Go to the project commits list (**Repository > Commits**). |
+| <kbd>g</kbd> + <kbd>n</kbd> | Go to the [repository graph](#repository-graph) page (**Repository > Graph**). |
+| <kbd>g</kbd> + <kbd>d</kbd> | Go to repository charts (**Repository > Charts**). |
+| <kbd>g</kbd> + <kbd>i</kbd> | Go to the project issues list (**Issues > List**). |
+| <kbd>i</kbd>                | Go to the New Issue page (**Issues**, click **New Issue** ). |
+| <kbd>g</kbd> + <kbd>b</kbd> | Go to the project issue boards list (**Issues > Boards**). |
+| <kbd>g</kbd> + <kbd>m</kbd> | Go to the project merge requests list (**Merge Requests**). |
+| <kbd>g</kbd> + <kbd>j</kbd> | Go to the CI/CD jobs list (**CI/CD > Jobs**). |
+| <kbd>g</kbd> + <kbd>l</kbd> | Go to the project metrics (**Operations > Metrics**). |
+| <kbd>g</kbd> + <kbd>e</kbd> | Go to the project environments (**Operations > Environments**). |
+| <kbd>g</kbd> + <kbd>k</kbd> | Go to the project Kubernetes cluster integration page (**Operations > Kubernetes**). Note that you must have at least [`maintainer` permissions](permissions.md) to access this page. |
+| <kbd>g</kbd> + <kbd>s</kbd> | Go to the project snippets list (**Snippets**). |
+| <kbd>g</kbd> + <kbd>w</kbd> | Go to the project wiki (**Wiki**), if enabled. |
+
+### Issues and Merge Requests
+
+These shortcuts are available when viewing issues and merge requests.
+
+| Keyboard Shortcut            | Description |
+| ---------------------------- | ----------- |
+| <kbd>e</kbd>                 | Edit description. |
+| <kbd>a</kbd>                 | Change assignee. |
+| <kbd>m</kbd>                 | Change milestone. |
+| <kbd>l</kbd>                 | Change label. |
+| <kbd>r</kbd>                 | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. |
+| <kbd>n</kbd>                 | Move to next unresolved discussion (Merge requests only). |
+| <kbd>p</kbd>                 | Move to previous unresolved discussion (Merge requests only). |
+| <kbd>]</kbd> or <kbd>j</kbd> | Move to next file (Merge requests only). |
+| <kbd>[</kbd> or <kbd>k</kbd> | Move to previous file (Merge requests only). |
+
+### Project Files
+
+These shortcuts are available when browsing the files in a project (navigate to
+**Repository** > **Files**):
+
+| Keyboard Shortcut | Description |
+| ----------------- | ----------- |
+| <kbd>↑</kbd>      | Move selection up. |
+| <kbd>↓</kbd>      | Move selection down. |
+| <kbd>enter</kbd>  | Open selection. |
+| <kbd>esc</kbd>    | Go back to file list screen (only while searching for files, **Repository > Files** then click on **Find File**). |
+| <kbd>y</kbd>      | Go to file permalink (only while viewing a file). |
+
+### Web IDE
+
+These shortcuts are available when editing a file with the [Web IDE](project/web_ide/index.md):
+
+| Keyboard Shortcut                                       | Description |
+| ------------------------------------------------------- | ----------- |
+| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>p</kbd>     | Search for, and then open another file for editing. |
+| <kbd>⌘</kbd> (Mac) / <kbd>Ctrl</kbd> + <kbd>Enter</kbd> | Commit (when editing the commit message). |
+
+### Repository Graph
+
+These shortcuts are available when viewing the project [repository graph](project/repository/index.md#repository-graph)
+page (navigate to **Repository > Graph**):
+
+| Keyboard Shortcut                                                  | Description |
+| ------------------------------------------------------------------ | ----------- |
+| <kbd>←</kbd> or <kbd>h</kbd>                                       | Scroll left. |
+| <kbd>→</kbd> or <kbd>l</kbd>                                       | Scroll right. |
+| <kbd>↑</kbd> or <kbd>k</kbd>                                       | Scroll up. |
+| <kbd>↓</kbd> or <kbd>j</kbd>                                       | Scroll down. |
+| <kbd>Shift</kbd> + <kbd>↑</kbd> or <kbd>Shift</kbd> + <kbd>k</kbd> | Scroll to top. |
+| <kbd>Shift</kbd> + <kbd>↓</kbd> or <kbd>Shift</kbd> + <kbd>j</kbd> | Scroll to bottom. |
+
+### Wiki pages
+
+This shortcut is available when viewing a [wiki page](project/wiki/index.md):
+
+| Keyboard Shortcut | Description |
+| ----------------- | ----------- |
+| <kbd>e</kbd>      | Edit wiki page. |
+
+## Epics **(ULTIMATE)**
+
+These shortcuts are available when viewing [Epics](group/epics/index.md):
+
+| Keyboard Shortcut | Description |
+| ----------------- | ----------- |
+| <kbd>r</kbd>      | Start writing a comment. If any text is selected, it will be quoted in the comment. Can't be used to reply within a thread. |
+| <kbd>e</kbd>      | Edit description. |
+| <kbd>l</kbd>      | Change label. |
diff --git a/doc/user/todos.md b/doc/user/todos.md
new file mode 100644
index 00000000000..22a6d07aedb
--- /dev/null
+++ b/doc/user/todos.md
@@ -0,0 +1,142 @@
+---
+disqus_identifier: 'https://docs.gitlab.com/ee/workflow/todos.html'
+---
+
+# GitLab To-Do List
+
+> [Introduced][ce-2817] in GitLab 8.5.
+
+When you log into GitLab, you normally want to see where you should spend your
+time, take some action, or know what you need to keep an eye on without
+a huge pile of e-mail notifications. GitLab is where you do your work,
+so being able to get started quickly is important.
+
+Your To-Do List offers a chronological list of items that are waiting for your input, all
+in a simple dashboard.
+
+![To Do screenshot showing a list of items to check on](img/todos_index.png)
+
+You can quickly access your To-Do List by clicking the checkmark icon next to the
+search bar in the top navigation. If the count is:
+
+- Less than 100, the number in blue is the number of To-Do items.
+- 100 or more, the number displays as 99+. The exact number displays
+  on the To-Do List.
+you still have open. Otherwise, the number displays as 99+. The exact number
+displays on the To-Do List.
+
+![To Do icon](img/todos_icon.png)
+
+## What triggers a To Do
+
+A To Do displays on your To-Do List when:
+
+- An issue or merge request is assigned to you
+- You are `@mentioned` in the description or comment of an:
+  - Issue
+  - Merge Request
+  - Epic **(ULTIMATE)**
+- You are `@mentioned` in a comment on a commit
+- A job in the CI pipeline running for your merge request failed, but this
+  job is not allowed to fail
+- An open merge request becomes unmergeable due to conflict, and you are either:
+  - The author
+  - Have set it to automatically merge once the pipeline succeeds
+
+To-do triggers are not affected by [GitLab Notification Email settings](../workflow/notifications.md).
+
+NOTE: **Note:**
+When a user no longer has access to a resource related to a To Do (like an issue, merge request, project, or group) the related To-Do items are deleted within the next hour for security reasons. The delete is delayed to prevent data loss, in case the user's access was revoked by mistake.
+
+### Directly addressing a To Do
+
+> [Introduced][ce-7926] in GitLab 9.0.
+
+If you are mentioned at the start of a line, the To Do you receive will be listed
+as 'directly addressed'. For example, in this comment:
+
+```markdown
+@alice What do you think? cc: @bob
+
+- @carol can you please have a look?
+
+>>>
+@dan what do you think?
+>>>
+
+@erin @frank thank you!
+```
+
+The people receiving directly addressed To-Do items are `@alice`, `@erin`, and
+`@frank`. Directly addressed To-Do items only differ from mentions in their type
+for filtering purposes; otherwise, they appear as normal.
+
+### Manually creating a To Do
+
+You can also add the following to your To-Do List by clicking the **Add a To Do** button on an:
+
+- Issue
+- Merge Request
+- Epic **(ULTIMATE)**
+
+![Adding a To Do from the issuable sidebar](img/todos_add_todo_sidebar.png)
+
+## Marking a To Do as done
+
+Any action to the following will mark the corresponding To Do as done:
+
+- Issue
+- Merge Request
+- Epic **(ULTIMATE)**
+
+Actions that dismiss To-Do items include:
+
+- Changing the assignee
+- Changing the milestone
+- Adding/removing a label
+- Commenting on the issue
+
+Your To-Do List is personal, and items are only marked as done if the action comes from
+you. If you close the issue or merge request, your To Do is automatically
+marked as done.
+
+To prevent other users from closing issues without you being notified, if someone else closes, merges, or takes action on the any of the following, your To Do will remain pending:
+
+- Issue
+- Merge request
+- Epic **(ULTIMATE)**
+
+There is just one To Do for each of these, so mentioning a user a hundred times in an issue will only trigger one To Do.
+
+If no action is needed, you can manually mark the To Do as done by clicking the
+corresponding **Done** button, and it will disappear from your To-Do List.
+
+![A To Do in the To-Do List](img/todos_todo_list_item.png)
+
+You can also mark a To Do as done by clicking the **Mark as done** button in the sidebar of the following:
+
+- Issue
+- Merge Request
+- Epic **(ULTIMATE)**
+
+![Mark as done from the issuable sidebar](img/todos_mark_done_sidebar.png)
+
+You can mark all your To-Do items as done at once by clicking the **Mark all as
+done** button.
+
+## Filtering your To-Do List
+
+There are four kinds of filters you can use on your To-Do List.
+
+| Filter  | Description |
+| ------- | ----------- |
+| Project | Filter by project |
+| Group   | Filter by group |
+| Author  | Filter by the author that triggered the To Do |
+| Type    | Filter by issue, merge request, or epic **(ULTIMATE)** |
+| Action  | Filter by the action that triggered the To Do |
+
+You can also filter by more than one of these at the same time. The possible Actions are `Any Action`, `Assigned`, `Mentioned`, `Added`, `Pipelines`, and `Directly Addressed`, [as described above](#what-triggers-a-to-do).
+
+[ce-2817]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/2817
+[ce-7926]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/7926