Merge branch 'docs-repo-merge-4-workflow' into 'master'

Docs: Merge EE doc/​workflow to CE

See merge request gitlab-org/gitlab-ce!27622

doc/user/project/issues/issue_data_and_actions.md

@@ -90,7 +90,7 @@ If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown me
 
 - Assign a weight. Larger values are used to indicate more effort is required to complete the issue. Only positive values or zero are allowed.
 
-Learn more in the [Issue Weight documentation](https://docs.gitlab.com/ee/workflow/issue_weight.html).
+Learn more in the [Issue Weight documentation](../../../workflow/issue_weight.md).
 
 #### 9. Participants
 
@@ -103,7 +103,7 @@ Learn more in the [Issue Weight documentation](https://docs.gitlab.com/ee/workfl
 - Unsubscribe: if you are receiving notifications on that issue but no
   longer want to receive them, unsubscribe from it.
 
-Read more in the [notifications documentation](../../../workflow/notifications.md#issue--merge-request-events).
+Read more in the [notifications documentation](../../../workflow/notifications.md#issue--epics--merge-request-events).
 
 #### 11. Reference
 

doc/workflow/README.md

@@ -13,12 +13,15 @@ comments: false
 - [Groups](../user/group/index.md)
 - Issues - 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.
+  - [Exporting Issues](https://docs.gitlab.com/ee/user/project/issues/csv_export.html) **[STARTER]** Export issues as a CSV, emailed as an attachment.
   - [Confidential issues](../user/project/issues/confidential_issues.md)
   - [Due date for issues](../user/project/issues/due_dates.md)
 - [Issue Board](../user/project/issue_board.md)
 - [Keyboard shortcuts](shortcuts.md)
 - [File finder](file_finder.md)
+- [File lock](https://docs.gitlab.com/ee/user/project/file_lock.html) **[PREMIUM]**
 - [Labels](../user/project/labels.md)
+- [Issue weight](https://docs.gitlab.com/ee/workflow/issue_weight.html) **[STARTER]**
 - [Notification emails](notifications.md)
 - [Projects](../user/project/index.md)
 - [Project forking workflow](forking_workflow.md)
@@ -41,6 +44,9 @@ comments: false
   - [Merge requests versions](../user/project/merge_requests/versions.md)
   - ["Work In Progress" merge requests](../user/project/merge_requests/work_in_progress_merge_requests.md)
   - [Fast-forward merge requests](../user/project/merge_requests/fast_forward_merge.md)
+  - [Merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) **[STARTER]**
+- [Repository mirroring](repository_mirroring.md) **[STARTER]**
+- [Service Desk](https://docs.gitlab.com/ee/user/project/service_desk.html) **[PREMIUM]**
 - [Manage large binaries with Git LFS](lfs/manage_large_binaries_with_git_lfs.md)
 - [Importing from SVN, GitHub, Bitbucket, etc](importing/README.md)
 - [Todos](todos.md)

doc/workflow/ff_merge.md

+---
+redirect_to: '../user/project/merge_requests/fast_forward_merge.md'
+---
+
+This document was moved to [user/project/merge_requests/fast_forward_merge](../user/project/merge_requests/fast_forward_merge.md).

doc/workflow/git_annex.md

+# Git annex
+
+> **Warning:** GitLab has [completely
+removed][deprecate-annex-issue] in GitLab 9.0 (2017/03/22).
+Read through the [migration guide from git-annex to git-lfs][guide].
+
+The biggest limitation of Git, compared to some older centralized version
+control systems, has been the maximum size of the repositories.
+
+The general recommendation is to not have Git repositories larger than 1GB to
+preserve performance. Although GitLab has no limit (some repositories in GitLab
+are over 50GB!), we subscribe to the advice to keep repositories as small as
+you can.
+
+Not being able to version control large binaries is a big problem for many
+larger organizations.
+Videos, photos, audio, compiled binaries and many other types of files are too
+large. As a workaround, people keep artwork-in-progress in a Dropbox folder and
+only check in the final result. This results in using outdated files, not
+having a complete history and increases the risk of losing work.
+
+This problem is solved in GitLab Enterprise Edition by integrating the
+[git-annex] application.
+
+`git-annex` allows managing large binaries with Git without checking the
+contents into Git.
+You check-in only a symlink that contains the SHA-1 of the large binary. If you
+need the large binary, you can sync it from the GitLab server over `rsync`, a
+very fast file copying tool.
+
+## GitLab git-annex Configuration
+
+`git-annex` is disabled by default in GitLab. Below you will find the
+configuration options required to enable it.
+
+### Requirements
+
+`git-annex` needs to be installed both on the server and the client side.
+
+For Debian-like systems (e.g., Debian, Ubuntu) this can be achieved by running:
+
+```
+sudo apt-get update && sudo apt-get install git-annex
+```
+
+For RedHat-like systems (e.g., CentOS, RHEL) this can be achieved by running:
+
+```
+sudo yum install epel-release && sudo yum install git-annex
+```
+
+### Configuration for Omnibus packages
+
+For omnibus-gitlab packages, only one configuration setting is needed.
+The Omnibus package will internally set the correct options in all locations.
+
+1.  In `/etc/gitlab/gitlab.rb` add the following line:
+
+    ```ruby
+    gitlab_shell['git_annex_enabled'] = true
+    ```
+
+1.  Save the file and [reconfigure GitLab][] for the changes to take effect.
+
+### Configuration for installations from source
+
+There are 2 settings to enable git-annex on your GitLab server.
+
+One is located in `config/gitlab.yml` of the GitLab repository and the other
+one is located in `config.yml` of gitlab-shell.
+
+1.  In `config/gitlab.yml` add or edit the following lines:
+
+    ```yaml
+    gitlab_shell:
+      git_annex_enabled: true
+    ```
+
+1.  In `config.yml` of gitlab-shell add or edit the following lines:
+
+    ```yaml
+    git_annex_enabled: true
+    ```
+
+1.  Save the files and [restart GitLab][] for the changes to take effect.
+
+## Using GitLab git-annex
+
+> **Note:**
+> Your Git remotes must be using the SSH protocol, not HTTP(S).
+
+Here is an example workflow of uploading a very large file and then checking it
+into your Git repository:
+
+```bash
+git clone git@example.com:group/project.git
+
+git annex init 'My Laptop'       # initialize the annex project and give an optional description
+cp ~/tmp/debian.iso ./           # copy a large file into the current directory
+git annex add debian.iso         # add the large file to git annex
+git commit -am "Add Debian iso"  # commit the file metadata
+git annex sync --content         # sync the Git repo and large file to the GitLab server
+```
+
+The output should look like this:
+
+```
+commit
+On branch master
+Your branch is ahead of 'origin/master' by 1 commit.
+  (use "git push" to publish your local commits)
+nothing to commit, working tree clean
+ok
+pull origin
+remote: Counting objects: 5, done.
+remote: Compressing objects: 100% (4/4), done.
+remote: Total 5 (delta 2), reused 0 (delta 0)
+Unpacking objects: 100% (5/5), done.
+From example.com:group/project
+   497842b..5162f80  git-annex  -> origin/git-annex
+ok
+(merging origin/git-annex into git-annex...)
+(recording state in git...)
+copy debian.iso (checking origin...) (to origin...)
+SHA256E-s26214400--8092b3d482fb1b7a5cf28c43bc1425c8f2d380e86869c0686c49aa7b0f086ab2.iso
+     26,214,400 100%  638.88kB/s    0:00:40 (xfr#1, to-chk=0/1)
+ok
+pull origin
+ok
+(recording state in git...)
+push origin
+Counting objects: 15, done.
+Delta compression using up to 4 threads.
+Compressing objects: 100% (13/13), done.
+Writing objects: 100% (15/15), 1.64 KiB | 0 bytes/s, done.
+Total 15 (delta 1), reused 0 (delta 0)
+To example.com:group/project.git
+ * [new branch]      git-annex -> synced/git-annex
+ * [new branch]      master -> synced/master
+ok
+```
+
+Your files can be found in the `master` branch, but you'll notice that there
+are more branches created by the `annex sync` command.
+
+Git Annex will also create a new directory at `.git/annex/` and will record the
+tracked files in the `.git/config` file. The files you assign to be tracked
+with `git-annex` will not affect the existing `.git/config` records. The files
+are turned into symbolic links that point to data in `.git/annex/objects/`.
+
+The `debian.iso` file in the example will contain the symbolic link:
+
+```
+.git/annex/objects/ZW/1k/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.png/SHA256E-s82701--6384039733b5035b559efd5a2e25a493ab6e09aabfd5162cc03f6f0ec238429d.iso
+```
+
+Use `git annex info` to retrieve the information about the local copy of your
+repository.
+
+---
+
+Downloading a single large file is also very simple:
+
+```bash
+git clone git@gitlab.example.com:group/project.git
+
+git annex sync             # sync Git branches but not the large file
+git annex get debian.iso   # download the large file
+```
+
+To download all files:
+
+```bash
+git clone git@gitlab.example.com:group/project.git
+
+git annex sync --content  # sync Git branches and download all the large files
+```
+
+By using `git-annex` without GitLab, anyone that can access the server can also
+access the files of all projects, but GitLab Annex ensures that you can only
+access files of projects you have access to (developer, maintainer, or owner role).
+
+## How it works
+
+Internally GitLab uses [GitLab Shell] to handle SSH access and this was a great
+integration point for `git-annex`.
+There is a setting in gitlab-shell so you can disable GitLab Annex support
+if you want to.
+
+## Troubleshooting tips
+
+Differences in version of `git-annex` on the GitLab server and on local machines
+can cause `git-annex` to raise unpredicted warnings and errors.
+
+Consult the [Annex upgrade page][annex-upgrade] for more information about
+the differences between versions. You can find out which version is installed
+on your server by navigating to <https://pkgs.org/download/git-annex> and
+searching for your distribution.
+
+Although there is no general guide for `git-annex` errors, there are a few tips
+on how to go around the warnings.
+
+### git-annex-shell: Not a git-annex or gcrypt repository.
+
+This warning can appear on the initial `git annex sync --content` and is caused
+by differences in `git-annex-shell`. You can read more about it
+[in this git-annex issue][issue].
+
+One important thing to note is that despite the warning, the `sync` succeeds
+and the files are pushed to the GitLab repository.
+
+If you get hit by this, you can run the following command inside the repository
+that the warning was raised:
+
+```
+git config remote.origin.annex-ignore false
+```
+
+Consecutive runs of `git annex sync --content` **should not** produce this
+warning and the output should look like this:
+
+```
+commit  ok
+pull origin
+ok
+pull origin
+ok
+push origin
+```
+
+[annex-upgrade]: https://git-annex.branchable.com/upgrades/
+[deprecate-annex-issue]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1648
+[git-annex]: https://git-annex.branchable.com/ "git-annex website"
+[gitlab shell]: https://gitlab.com/gitlab-org/gitlab-shell "GitLab Shell repository"
+[guide]: lfs/migrate_from_git_annex_to_git_lfs.html
+[issue]: https://git-annex.branchable.com/forum/Error_from_git-annex-shell_on_creation_of_gcrypt_special_remote/ "git-annex issue"
+[reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure
+[restart GitLab]: ../administration/restart_gitlab.md#installations-from-source

doc/workflow/git_lfs.md

+---
+redirect_to: 'lfs/manage_large_binaries_with_git_lfs.md'
+---
+
+This document was moved to [another location](lfs/manage_large_binaries_with_git_lfs.md).

doc/workflow/issue_weight.md

+# Issue Weight **[STARTER]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/76)
+> in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3.
+
+When you have a lot of issues, it can be hard to get an overview.
+By adding a weight to each issue, you can get a better idea of how much time,
+value or complexity a given issue has or will cost.
+
+You can set the weight of an issue during its creation, by simply changing the
+value in the dropdown menu. You can set it to a non-negative integer
+value from 0, 1, 2, and so on. (The database stores a 4-byte value, so the 
+upper bound is essentially limitless).
+You can remove weight from an issue
+as well.
+
+This value will appear on the right sidebar of an individual issue, as well as
+in the issues page next to a distinctive balance scale icon.
+
+As an added bonus, you can see the total sum of all issues on the milestone page.
+
+![issue page](issue_weight/issue.png)

doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md

+# Migration guide from Git Annex to Git LFS
+
+>**Note:**
+Git Annex support [has been removed][issue-remove-annex] in GitLab Enterprise
+Edition 9.0 (2017/03/22).
+
+Both [Git Annex][] and [Git LFS][] are tools to manage large files in Git.
+
+## History
+
+Git Annex [was introduced in GitLab Enterprise Edition 7.8][post-3], at a time
+where Git LFS didn't yet exist. A few months later, GitLab brought support for
+Git LFS in [GitLab 8.2][post-2] and is available for both Community and
+Enterprise editions.
+
+## Differences between Git Annex and Git LFS
+
+Some items below are general differences between the two protocols and some are
+ones that GitLab developed.
+
+- Git Annex works only through SSH, whereas Git LFS works both with SSH and HTTPS
+  (SSH support was added in GitLab 8.12).
+- Annex files are stored in a sub-directory of the normal repositories, whereas
+  LFS files are stored outside of the repositories in a place you can define.
+- Git Annex requires a more complex setup, but has much more options than Git
+  LFS. You can compare the commands each one offers by running `man git-annex`
+  and `man git-lfs`.
+- Annex files cannot be browsed directly in GitLab's interface, whereas LFS
+  files can.
+
+## Migration steps
+
+>**Note:**
+Since Git Annex files are stored in a sub-directory of the normal repositories
+(`.git/annex/objects`) and LFS files are stored outside of the repositories,
+they are not compatible as they are using a different scheme. Therefore, the
+migration has to be done manually per repository.
+
+There are basically two steps you need to take in order to migrate from Git
+Annex to Git LFS.
+
+### TL; DR
+
+If you know what you are doing and want to skip the reading, this is what you
+need to do (we assume you have [git-annex enabled][annex-gitlab-use] in your
+repository and that you have made backups in case something goes wrong).
+Fire up a terminal, navigate to your Git repository and:
+
+
+1. Disable `git-annex`:
+
+    ```bash
+    git annex sync --content
+    git annex direct
+    git annex uninit
+    git annex indirect
+    ```
+
+1. Enable `git-lfs`:
+
+    ```
+    git lfs install
+    git lfs track <files>
+    git add .
+    git commit -m "commit message"
+    git push
+    ```
+
+### Disabling Git Annex in your repo
+
+Before changing anything, make sure you have a backup of your repository first.
+There are a couple of ways to do that, but you can simply clone it to another
+local path and maybe push it to GitLab if you want a remote backup as well.
+Here you'll find a guide on
+[how to back up a **git-annex** repository to an external hard drive][bkp-ext-drive].
+
+Since Annex files are stored as objects with symlinks and cannot be directly
+modified, we need to first remove those symlinks.
+
+>**Note:**
+Make sure the you read about the [`direct` mode][annex-direct] as it contains
+useful information that may fit in your use case. Note that `annex direct` is
+deprecated in Git Annex version 6, so you may need to upgrade your repository
+if the server also has Git Annex 6 installed. Read more in the
+[Git Annex troubleshooting tips][annex-tips] section.
+
+1. Backup your repository
+
+    ```bash
+    cd repository
+    git annex sync --content
+    cd ..
+    git clone repository repository-backup
+    cd repository-backup
+    git annex get
+    cd ..
+    ```
+
+1. Use `annex direct`:
+
+    ```bash
+    cd repository
+    git annex direct
+    ```
+
+    The output should be similar to this:
+
+    ```bash
+    commit
+    On branch master
+    Your branch is up-to-date with 'origin/master'.
+    nothing to commit, working tree clean
+    ok
+    direct debian.iso ok
+    direct  ok
+    ```
+
+1. Disable Git Annex with [`annex uninit`][uninit]:
+
+    ```bash
+    git annex uninit
+    ```
+
+    The output should be similar to this:
+
+    ```bash
+    unannex debian.iso ok
+    Deleted branch git-annex (was 2534d2c).
+    ```
+
+    This will `unannex` every file in the repository, leaving the original files.
+
+1. Switch back to `indirect` mode:
+
+    ```bash
+    git annex indirect
+    ```
+
+    The output should be similar to this:
+
+    ```bash
+    (merging origin/git-annex into git-annex...)
+    (recording state in git...)
+    commit  (recording state in git...)
+
+    ok
+    (recording state in git...)
+    [master fac3194] commit before switching to indirect mode
+     1 file changed, 1 deletion(-)
+     delete mode 120000 alpine-virt-3.4.4-x86_64.iso
+    ok
+    indirect  ok
+    ok
+    ```
+
+---
+
+At this point, you have two options. Either add, commit and push the files
+directly back to GitLab or switch to Git LFS. We will tackle the LFS switch in
+the next section.
+
+### Enabling Git LFS in your repo
+
+Git LFS is enabled by default on all GitLab products (GitLab CE, GitLab EE,
+GitLab.com), therefore, you don't need to do anything server-side.
+
+1. First, make sure you have `git-lfs` installed locally:
+
+    ```bash
+    git lfs help
+    ```
+
+    If the terminal doesn't prompt you with a full response on `git-lfs` commands,
+    [install the Git LFS client][install-lfs] first.
+
+1. Inside the repo, run the following command to initiate LFS:
+
+    ```bash
+    git lfs install
+    ```
+
+1. Enable `git-lfs` for the group of files you want to track. You
+   can track specific files, all files containing the same extension, or an
+   entire directory:
+
+    ```bash
+    git lfs track images/01.png   # per file
+    git lfs track **/*.png        # per extension
+    git lfs track images/         # per directory
+    ```
+
+    Once you do that, run `git status` and you'll see `.gitattributes` added
+    to your repo. It collects all file patterns that you chose to track via
+    `git-lfs`.
+
+1. Add the files, commit and push them to GitLab:
+
+    ```bash
+    git add .
+    git commit -m "commit message"
+    git push
+    ```
+
+    If your remote is set up with HTTP, you will be asked to enter your login
+    credentials. If you have [2FA enabled][2fa], make sure to use a
+    [personal access token][token] instead of your password.
+
+## Removing the Git Annex branches
+
+After the migration finishes successfully, you can remove all `git-annex`
+related branches from your repository.
+
+On GitLab, navigate to your project's **Repository ➔ Branches** and delete all
+branches created by Git Annex: `git-annex`, and all under `synced/`.
+
+![repository branches](images/git-annex-branches.png)
+
+You can also do this on the commandline with:
+
+    ```bash
+    git branch -d synced/master
+    git branch -d synced/git-annex
+    git push origin :synced/master
+    git push origin :synced/git-annex
+    git push origin :git-annex
+    git remote prune origin
+    ```
+
+If there are still some Annex objects inside your repository (`.git/annex/`)
+or references inside `.git/config`, run `annex uninit` again:
+
+```bash
+git annex uninit
+```
+
+## Further Reading
+
+- (Blog Post) [Getting Started with Git FLS][post-1]
+- (Blog Post) [Announcing LFS Support in GitLab][post-2]
+- (Blog Post) [GitLab Annex Solves the Problem of Versioning Large Binaries with Git][post-3]
+- (GitLab Docs) [Git Annex][doc-1]
+- (GitLab Docs) [Git LFS][doc-2]
+
+[2fa]: ../../user/profile/account/two_factor_authentication.md
+[token]: ../../user/profile/account/two_factor_authentication.html#personal-access-tokens
+[annex-tips]: ../git_annex.html#troubleshooting-tips
+[annex-direct]: https://git-annex.branchable.com/direct_mode/
+[annex-gitlab-use]: ../git_annex.md#using-gitlab-git-annex
+[annex-ee]: https://docs.gitlab.com/ee/workflow/git_annex.html
+[bkp-ext-drive]: https://www.thomas-krenn.com/en/wiki/Git-annex_Repository_on_an_External_Hard_Drive
+[doc-1]: https://docs.gitlab.com/ee/workflow/git_annex.html
+[doc-2]: https://docs.gitlab.com/ee/workflow/lfs/manage_large_binaries_with_git_lfs.html
+[Git Annex]: http://git-annex.branchable.com/
+[Git LFS]: https://git-lfs.github.com/
+[install-lfs]: https://git-lfs.github.com/
+[issue-remove-annex]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1648
+[lfs-track]: https://about.gitlab.com/2017/01/30/getting-started-with-git-lfs-tutorial/#tracking-files-with-lfs
+[post-1]: https://about.gitlab.com/2017/01/30/getting-started-with-git-lfs-tutorial/
+[post-2]: https://about.gitlab.com/2015/11/23/announcing-git-lfs-support-in-gitlab/
+[post-3]: https://about.gitlab.com/2015/02/17/gitlab-annex-solves-the-problem-of-versioning-large-binaries-with-git/
+[uninit]: https://git-annex.branchable.com/git-annex-uninit/

doc/workflow/merge_request_approvals.md

+---
+redirect_to: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html'
+---
+
+This document was moved to [user/project/merge_requests/merge_request_approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html).

doc/workflow/notifications.md

@@ -73,18 +73,18 @@ Below is the table of events users can be notified of:
 | Group access level changed   | User                                                              | Sent when user group access level is changed |
 | Project moved                | Project members [1]                                               | [1] not disabled |
 
-### Issue / Merge request events
+### Issue / Epics / Merge request events
 
 In most of the below cases, the notification will be sent to:
 
 - Participants:
   - the author and assignee of the issue/merge request
   - authors of comments on the issue/merge request
-  - anyone mentioned by `@username` in the issue/merge request title or description
-  - anyone mentioned by `@username` in any of the comments on the issue/merge request
-     ...with notification level "Participating" or higher
+  - anyone mentioned by `@username` in the title or description of the issue, merge request or epic **[ULTIMATE]**
+  - anyone with notification level "Participating" or higher that is mentioned by `@username`
+    in any of the comments on the issue, merge request, or epic **[ULTIMATE]**
 - Watchers: users with notification level "Watch"
-- Subscribers: anyone who manually subscribed to the issue/merge request
+- Subscribers: anyone who manually subscribed to the issue, merge request, or epic **[ULTIMATE]**
 - Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below
 
 | Event                  | Sent to |
@@ -107,6 +107,9 @@ In most of the below cases, the notification will be sent to:
 | New comment            | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher |
 | Failed pipeline        | The author of the pipeline |
 | Successful pipeline    | The author of the pipeline, if they have the custom notification setting for successful pipelines set |
+| New epic **[ULTIMATE]** |        |
+| Close epic **[ULTIMATE]** |      |
+| Reopen epic **[ULTIMATE]** |     |
 
 In addition, if the title or description of an Issue or Merge Request is
 changed, notifications will be sent to any **new** mentions by `@username` as

doc/workflow/rebase_before_merge.md

+---
+redirect_to: '../user/project/merge_requests/fast_forward_merge.md'
+---
+
+This document was moved to [another location](../user/project/merge_requests/fast_forward_merge.md).

doc/workflow/shortcuts.md

@@ -85,6 +85,14 @@ You can see GitLab's keyboard shortcuts by using 'shift + ?'
 | <kbd>]</kbd> or <kbd>j</kbd> | Move to next file |
 | <kbd>[</kbd> or <kbd>k</kbd> | Move to previous file |
 
+## Epics **[ULTIMATE]**
+
+| Keyboard Shortcut | Description |
+| ----------------- | ----------- |
+| <kbd>r</kbd> | Reply (quoting selected text) |
+| <kbd>e</kbd> | Edit description |
+| <kbd>l</kbd> | Change label |
+
 ## Wiki pages
 
 | Keyboard Shortcut | Description |

doc/workflow/todos.md

@@ -25,9 +25,8 @@ will still be shown in the body of the _To do_ tab.
 
 A Todo appears in your Todos dashboard when:
 
-- an issue or merge request is assigned to you,
-- you are `@mentioned` in an issue or merge request, be it the description of
-  the issue/merge request or in a comment,
+- an issue or merge request is assigned to you
+- you are `@mentioned` in the description or in a comment of an issue, merge request, or 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.
@@ -63,14 +62,14 @@ for filtering; otherwise, they appear as normal.
 
 ### Manually creating a Todo
 
-You can also add an issue or merge request to your Todos dashboard by clicking
-the "Add todo" button in the issue or merge request sidebar.
+You can also add an issue, merge request or epic to your Todos dashboard by clicking
+the "Add todo" button in the sidebar of the issue, merge request, or epic **[ULTIMATE]**.
 
 ![Adding a Todo from the issuable sidebar](img/todos_add_todo_sidebar.png)
 
 ## Marking a Todo as done
 
-Any action to the corresponding issue or merge request will mark your Todo as
+Any action to the corresponding issue, merge request or epic **[ULTIMATE]** will mark your Todo as
 **Done**. Actions that dismiss Todos include:
 
 - changing the assignee
@@ -84,10 +83,10 @@ Todos are personal, and they're only marked as done if the action is coming from
 you. If you close the issue or merge request, your Todo will automatically
 be marked as done.
 
-If someone else closes, merges, or takes action on the issue or merge
+If someone else closes, merges, or takes action on the issue, epic or merge
 request, your Todo will remain pending. This prevents other users from closing issues without you being notified.
 
-There is just one Todo per issue or merge request, so mentioning a user a
+There is just one Todo per issue, epic or merge request, so mentioning a user a
 hundred times in an issue will only trigger one Todo.
 
 ---
@@ -97,7 +96,7 @@ corresponding **Done** button, and it will disappear from your Todo list.
 
 ![A Todo in the Todos dashboard](img/todo_list_item.png)
 
-A Todo can also be marked as done from the issue or merge request sidebar using
+A Todo can also be marked as done from the issue, merge request or epic sidebar using
 the "Mark todo as done" button.
 
 ![Mark todo as done from the issuable sidebar](img/todos_mark_done_sidebar.png)
@@ -114,7 +113,7 @@ There are four kinds of filters you can use on your Todos dashboard.
 | Project | Filter by project |
 | Group   | Filter by group |
 | Author  | Filter by the author that triggered the Todo |
-| Type    | Filter by issue or merge request |
+| Type    | Filter by issue, merge request, or epic **[ULTIMATE]** |
 | Action  | Filter by the action that triggered the Todo |
 
 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-todo).