Merge branch 'cdybenko-master-patch-32482' into 'master'

Add roadmap filters to docs (FF enabled)

See merge request gitlab-org/gitlab!50202

doc/.vale/gitlab/spelling-exceptions.txt

@@ -404,6 +404,8 @@ reusability
 reverified
 reverifies
 reverify
+roadmap
+roadmaps
 rollout
 rollouts
 rsync

doc/user/group/roadmap/index.md

@@ -15,7 +15,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/214375) and later, the Roadmap also shows milestones in projects in a group.
 > - In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/212494) and later, milestone bars can be collapsed and expanded.
 
-Epics and milestones within a group containing a start date or due date can be visualized in a form
+Epics and milestones in a group containing a start date or due date can be visualized in a form
 of a timeline (that is, a Gantt chart). The Roadmap page shows the epics and milestones in a
 group, one of its subgroups, or a project in one of the groups.
 
@@ -24,14 +24,31 @@ When you hover over an epic bar, a popover appears with the epic's title, start
 weight completed.
 
 You can expand epics that contain child epics to show their child epics in the roadmap.
-You can click the chevron (**{chevron-down}**) next to the epic title to expand and collapse the child epics.
+You can click the chevron (**{chevron-down}**) next to the epic title to expand and collapse the
+child epics.
 
-On top of the milestone bars, you can see their title. When you hover a milestone bar or title, a popover appears with its title, start date and due date.
-You can also click the chevron (**{chevron-down}**) next to the **Milestones** heading to toggle the list of the milestone bars.
+On top of the milestone bars, you can see their title.
+When you hover over a milestone bar or title, a popover appears with its title, start date, and due
+date. You can also click the chevron (**{chevron-down}**) next to the **Milestones** heading to
+toggle the list of the milestone bars.
 
 ![roadmap view](img/roadmap_view_v13_2.png)
 
-A dropdown menu allows you to show only open or closed epics. By default, all epics are shown.
+## Sort and filter the Roadmap
+
+> - Filtering roadmaps by milestone [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218621) in GitLab 13.7.
+> - Filtering roadmaps by milestone is [deployed behind a feature flag](../../feature_flags.md), enabled by default.
+> - Filtering roadmaps by milestone is enabled on GitLab.com.
+> - Filtering roadmaps by milestone is recommended for production use.
+> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-filtering-roadmaps-by-milestone). **(PREMIUM ONLY)**
+
+WARNING:
+Filtering roadmaps by milestone might not be available to you. Check the **version history** note above for details.
+
+When you want to explore a roadmap, there are several ways to make it easier by sorting epics or
+filtering them by what's important for you.
+
+A dropdown menu lets you show only open or closed epics. By default, all epics are shown.
 
 ![epics state dropdown](img/epics_state_dropdown_v12_10.png)
 
@@ -45,8 +62,35 @@ You can sort epics in the Roadmap view by:
 Each option contains a button that toggles the sort order between **ascending** and **descending**.
 The sort option and order persist when browsing Epics, including the [epics list view](../epics/index.md).
 
+You can also filter epics in the Roadmap view by:
+
+- Author
+- Label
+- Milestone
+
+![roadmap date range in weeks](img/roadmap_filters_v13_7.png)
+
 Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics).
 
+### Enable or disable filtering roadmaps by milestone **(PREMIUM ONLY)**
+
+Filtering roadmaps by milestone is under development but ready for production use.
+It is deployed behind a feature flag that is **enabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
+can opt to disable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:async_filtering)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:async_filtering)
+```
+
 ## Timeline duration
 
 > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0.