Update Epics documentation following the Epic to Work Items migration
Summary
This issue will address the documentation updates needed for legacy epics before work item epics GA.
Pages to review and update
Following are the pages requiring updates as a part of the documentation update;
-
https://docs.gitlab.com/ee/user/group/epics/manage_epics.html -
https://docs.gitlab.com/ee/user/group/epics/linked_epics.html -
https://docs.gitlab.com/ee/api/resource_label_events.html#epics -
https://docs.gitlab.com/ee/api/resource_state_events.html#epics -
https://docs.gitlab.com/ee/api/events.html#target-types - Include Epic support now that it uses Work Items.
-
Additionally, we'd also need to add user documentation for Work Items API since https://docs.gitlab.com/ee/api/epics.html has been marked as deprecated and only natural replacement at the moment is Work Items API. Add epics as work items migration prerequisite (!168105 - merged) -
https://docs.gitlab.com/ee/user/project/settings/import_export.html#group-items-that-are-exported - Ensure that information about epic import is accurate following the migration.
-
In the Issues, merge requests, and epics table, change
**{dotted-circle}** No
to**{check-circle}** Yes
and add to the Action column:For epics, your administrator must have [enabled the new look for epics](epic_work_items.md).
-
~~(Not sure if planned before GA) Convert ~~~~https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/work_items/~~~~ to a ~~ dedicated GraphQL API page~~ and update links from other docs.~~ Created a follow up in Docs: Create dedicated page for Work Items Grap... (#506403)
TW:
-
Review merged and currently open MRs to add mention of required work items migration.
Implementation plan
-
Use the page Kushal created epic_work_items.html to store/add info on enabling the feature and risks.
-
Keep steps (for example, in
manage_epics.md
) as they are, because they're correct for people with the flag off, but add additional info where the steps are different. Similar to how we did this when some buttons were moved into a "More actions" dropdown: https://gitlab.com/gitlab-org/gitlab/-/blob/995bacac03be9d968cdcbc9ee29940d9eb00d822/doc/operations/incident_management/manage_incidents.md?plain=1#L229-L231For example:
If your administrator [enabled the new look for epics](epic_work_items.md), select <different button>.
You can use this in the prerequisites:
Your administrator must have [enabled the new look for epics](epic_work_items.md).
-
For new features, let’s treat the docs like for any new feature behind a feature flag, except let’s point to https://docs.gitlab.com/ee/user/group/epics/epic_work_items.html for info how to enable.
-
When relevant, add a comment near the doc to help Cmd-F it later:
<!-- When epics as work items are GA, [do X] (for example: the steps below should be the only ones here.) -->
Examples:
- Feature that has different steps: Docs Update: Link to full Roadmap view filtered... (!155865 - merged)
- New feature: Document assignees for epics (!163621 - merged)