Merge branch 'update-todo-vale-rule' into 'master'

Enforce proper usage of to-do item

See merge request gitlab-org/gitlab!46305

doc/.vale/gitlab/ToDo.yml

@@ -5,9 +5,10 @@
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: substitution
-message: 'Use "%s" instead of "%s" unless referring to the "Add a To Do" button in the UI.'
+message: 'Use "to-do item" in most cases, or "Add a to do" if referring to the UI button.'
 link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#feature-names
 level: warning
-ignorecase: true
+ignorecase: false
 swap:
-  'to dos': to-do items
+  '[Tt]o [Dd]o [Ii]tems?': to-do item
+  '\w* [Aa] [Tt]o [Dd]o': Add a to do

doc/api/epics.md

@@ -424,10 +424,10 @@ DELETE /groups/:id/epics/:epic_iid
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5"
 ```
 
-## Create a to do
+## Create a to-do item
 
-Manually creates a to do for the current user on an epic. If
-there already exists a to do for the user on that epic, status code `304` is
+Manually creates a to-do item for the current user on an epic. If
+there already exists a to-do item for the user on that epic, status code `304` is
 returned.
 
 ```plaintext

doc/api/issues.md

@@ -1507,10 +1507,10 @@ Example response:
 }
 ```
 
-## Create a to do
+## Create a to-do item
 
-Manually creates a to do for the current user on an issue. If
-there already exists a to do for the user on that issue, status code `304` is
+Manually creates a to-do item for the current user on an issue. If
+there already exists a to-do item for the user on that issue, status code `304` is
 returned.
 
 ```plaintext

doc/api/merge_requests.md

@@ -2089,10 +2089,10 @@ the `approvals_before_merge` parameter:
 }
 ```
 
-## Create a to do
+## Create a to-do item
 
-Manually creates a to do for the current user on a merge request.
-If there already exists a to do for the user on that merge request,
+Manually creates a to-do item for the current user on a merge request.
+If there already exists a to-do item for the user on that merge request,
 status code `304` is returned.
 
 ```plaintext

doc/api/todos.md

@@ -26,7 +26,7 @@ Parameters:
 | `project_id` | integer | no | The ID of a project |
 | `group_id` | integer | no | The ID of a group |
 | `state` | string | no | The state of the to do. Can be either `pending` or `done` |
-| `type` | string | no | The type of a to do. Can be either `Issue`, `MergeRequest`, `DesignManagement::Design` or `AlertManagement::Alert` |
+| `type` | string | no | The type of to-do item. Can be either `Issue`, `MergeRequest`, `DesignManagement::Design` or `AlertManagement::Alert` |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos"
@@ -187,7 +187,7 @@ Example Response:
 ]
 ```
 
-## Mark a to do as done
+## Mark a to-do item as done
 
 Marks a single pending to do given by its ID for the current user as done. The
 to do marked as done is returned in the response.
@@ -200,7 +200,7 @@ Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer | yes | The ID of a to do |
+| `id` | integer | yes | The ID of to-do item |
 
 ```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos/130/mark_as_done"

doc/operations/incident_management/alerts.md

@@ -186,19 +186,19 @@ After completing their portion of investigating or fixing the alert, users can
 unassign themselves from the alert. To remove an assignee, select **Edit** next to the **Assignee** dropdown menu
 and deselect the user from the list of assignees, or select **Unassigned**.
 
-### Create a to do from an alert
+### Create a to-do item from an alert
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1.
 
 You can manually create [To-Do list items](../../user/todos.md) for yourself
 from the Alert details screen, and view them later on your **To-Do List**. To
-add a to do:
+add a to-do item:
 
 1. To display the list of current alerts, navigate to **Operations > Alerts**.
 1. Select your desired alert to display its **Alert Management Details View**.
 1. Select the **Add a To-Do** button in the right sidebar:
 
-   ![Alert Details Add A To Do](./img/alert_detail_add_todo_v13_1.png)
+   ![Alert Details Add a To-Do](./img/alert_detail_add_todo_v13_1.png)
 
 Select the **To-Do List** **{todo-done}** in the navigation bar to view your current to-do list.
 

doc/operations/incident_management/incidents.md

@@ -190,7 +190,7 @@ adds a `missed::SLA` label to the incident.
 
 ## Incident Actions
 
-There are different actions avilable to help triage and respond to incidents.
+There are different actions available to help triage and respond to incidents.
 
 ### Assign incidents
 
@@ -200,9 +200,9 @@ Assign incidents to users that are actively responding. Select **Edit** in the r
 
 See [Incident List](#incident-list) for a full description of the severities available. Select **Edit** in the right-hand side bar to change the severity of an incident.
 
-### Add a to do
+### Add a to-do item
 
-Add a to-do for incidents that you want to track in your to-do list. Clicke the **Add a to do** button at the top of the right-hand side bar to add a to do.
+Add a to-do for incidents that you want to track in your to-do list. Click the **Add a to do** button at the top of the right-hand side bar to add a to-do item.
 
 ### Manage incidents from Slack
 

doc/user/project/issues/design_management.md

@@ -228,7 +228,7 @@ available in the **Resolved Comment** area at the bottom of the right sidebar.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198439) in GitLab 13.4.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/245074) in GitLab 13.5.
 
-Add a to do for a design by clicking **Add a To Do** on the design sidebar:
+Add a to-do item for a design by clicking **Add a to do** on the design sidebar:
 
 ![To-do button](img/design_todo_button_v13_5.png)
 

doc/user/project/quick_actions.md

@@ -74,7 +74,7 @@ The following quick actions are applicable to descriptions, discussions and thre
 | `/tableflip <comment>`                | ✓     | ✓             | ✓    | Append the comment with `(╯°□°)╯︵ ┻━┻`.                                                                                        |
 | `/target_branch <local branch name>`  |       | ✓             |      | Set target branch.                                                                                                              |
 | `/title <new title>`                  | ✓     | ✓             | ✓    | Change title.                                                                                                                  |
-| `/todo`                               | ✓     | ✓             | ✓    | Add a to do.                                                                                                                   |
+| `/todo`                               | ✓     | ✓             | ✓    | Add a to-do item.                                                                                                                   |
 | `/unassign @user1 @user2`             | ✓     | ✓             |      | Remove specific assignees. **(STARTER)**                                                                                       |
 | `/unassign`                           | ✓     | ✓             |      | Remove all assignees.                                                                                                          |
 | `/unlabel ~label1 ~label2` or `/remove_label ~label1 ~label2` | ✓     | ✓             | ✓    | Remove specified labels.                                                                         |

doc/user/todos.md

@@ -15,9 +15,9 @@ spend your time. This can include taking an action, or keeping track of things
 do your work, being able to get started quickly is important.
 
 Your *To-Do List* offers a chronological list of items waiting for your input
-(known as *to do items*) in a single dashboard.
+(known as *to-do items*) in a single dashboard.
 
-The To-Do List supports tracking [actions](#what-triggers-a-to-do) related to
+The To-Do List supports tracking [actions](#what-triggers-a-to-do-item) related to
 the following:
 
 - Issues
@@ -27,17 +27,17 @@ the following:
 ![to-do screenshot showing a list of items to check on](img/todos_index.png)
 
 You can access your To-Do List by clicking the To-Do List icon (**{task-done}**)
-next to the search bar in the top navigation. If the to do item count is:
+next to the search bar in the top navigation. If the to-do item count is:
 
-- *Less than 100*, the number in blue is the number of to do items.
+- *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 in the
   To-Do List.
 
 ![To Do icon](img/todos_icon.png)
 
-## What triggers a to do
+## What triggers a to-do item
 
-A to do item appears on your To-Do List when:
+A to-do item appears on your To-Do List when:
 
 - An issue or merge request is assigned to you.
 - You're `@mentioned` in the description or comment of an issue or merge request
@@ -60,19 +60,19 @@ When several trigger actions occur for the same user on the same object (for
 example, an issue), GitLab displays only the first action as a single to do
 item.
 
-To do item triggers aren't affected by [GitLab notification email settings](profile/notifications.md).
+To-do item triggers aren't affected by [GitLab notification email settings](profile/notifications.md).
 
 NOTE: **Note:**
-When a user no longer has access to a resource related to a to do item (such as
+When a user no longer has access to a resource related to a to-do item (such as
 an issue, merge request, project, or group), for security reasons GitLab
-deletes any related to do items within the next hour. Deletion is delayed to
+deletes any related to-do items within the next hour. Deletion is delayed to
 prevent data loss, in the case where a user's access is accidentally revoked.
 
-### Directly addressing a to do
+### Directly addressing a to-do item
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7926) in GitLab 9.0.
 
-If you're mentioned at the start of a line, the to do item you receive will be
+If you're mentioned at the start of a line, the to-do item you receive will be
 listed as *directly addressed*. For example, in the following comment:
 
 ```markdown
@@ -87,11 +87,11 @@ listed as *directly addressed*. For example, in the following comment:
 @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
+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
+### Manually creating a to-do item
 
 You can also add the following to your To-Do List by clicking the **Add a to do** button on an:
 
@@ -100,14 +100,14 @@ You can also add the following to your To-Do List by clicking the **Add a to do*
 - [Epic](group/epics/index.md) **(ULTIMATE)**
 - [Design](project/issues/design_management.md)
 
-![Adding a To Do from the issuable sidebar](img/todos_add_todo_sidebar.png)
+![Adding a to-do item from the issuable sidebar](img/todos_add_todo_sidebar.png)
 
-## Marking a to do as done
+## Marking a to-do item as done
 
 Any action to an issue or merge request (or epic **(ULTIMATE)**) will mark its
-corresponding to do item as done.
+corresponding to-do item as done.
 
-Actions that dismiss to do items include:
+Actions that dismiss to-do items include:
 
 - Changing the assignee
 - Changing the milestone
@@ -115,28 +115,28 @@ Actions that dismiss to do items include:
 - Commenting on the issue
 
 Your To-Do List is personal, and items are only marked as done if you take
-action. If you close the issue or merge request, your to do item is marked as
+action. If you close the issue or merge request, your to-do item is marked as
 done.
 
 To prevent other users from closing issues without you being notified, if
 someone else closes, merges, or takes action on an issue or merge request (or
-epic **(ULTIMATE)**), your to do item remains pending.
+epic **(ULTIMATE)**), your to-do item remains pending.
 
-There's just one to do item for each of these, so mentioning a user many times
-in an issue only triggers one to do item.
+There's just one to-do item for each of these, so mentioning a user many times
+in an issue only triggers one to-do item.
 
-If no action is needed, you can manually mark the to do item as done by
+If no action is needed, you can manually mark the to-do item as done by
 clicking its corresponding **Done** button to have GitLab remove the item 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 item as done by clicking the **Mark as done** button
+You can also mark a to-do item as done by clicking the **Mark as done** button
 in the sidebar of an issue or merge request (or 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
+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
@@ -152,7 +152,7 @@ You can use the following types of filters with your To-Do List:
 | 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 previously
-described [triggering actions](#what-triggers-a-to-do) include:
+described [triggering actions](#what-triggers-a-to-do-item) include:
 
 - Any action
 - Assigned