Skip to content

[🎨 Design] Work Items - Epic Milestone

Summary

Design issue for the addition of Milestones for Epics, and the various considerations that come with the new feature.

Proposal

ℹ️ Some of the work for this is dependent on the release of the Consolidated List, which means this feature will not be released until after that work is complete.

We plan to leverage the same Milestone widget that is being used for other work item types (ex: Issues). This means assigning, editing, and removing Milestones will be handled in the same way on detail pages.

With this new attribute available for Epics, the following other items need to be considered:

MVC Acceptance Criteria

Epic Lists

⚠️ Note: these changes are only proposed for the new work items list, and not meant to be addressed on the legacy version.

  1. Milestone values should be displayed in items within the work item list.
  2. Users should be able to filter the List by Milestone.

Epic Boards

  1. Milestone values should be displayed on the items (cards) within the board.
  2. The sidebar/drawer (when selecting a card item) should contain a widget to view and update the Milestone.
    1. Since we are close to releasing the contextual view (drawer) to customers, this should come with the default drawer experience and not require extra work. This means we should not work to make this available in the legacy Boards drawer unless the contextual view ends up getting delayed for some reason.
  3. Users should be able to filter the board by a Milestone option.
  4. Users should be able to scope a list by a Milestone option.

Epic Detail

  1. Milestone values should be displayed on items within the Child items widget.
  2. Milestone values should be displayed on items within the Linked items widget.
  3. Handling of Milestone value when an Issue is promoted to Epic.
    1. If that Milestone value is allowed for the Epic (currently it would need to be a group milestone), maintain the Milestone value for the promoted Epic.
    2. If that Milestone value is not allowed, inform the user within the Change type modal alert that the Milestone is not available (see included design)

Milestone Inheritance (creation flow)

Child widget (if this is done before updating to use the create modal)

  1. When creating a child item (using Child items widget) from an Epic that has a Milestone defined, automatically apply that Milestone to the new child item upon creation.
  2. When adding an existing item (using Child items widget) as a child of an Epic that has a Milestone defined, we will not automatically update the milestone of that child item. This matches how Tasks are handled today, and we will look at potentially modifying this behavior for all items in #367460

Create modal & full page

  1. When creating a child item (using Child items widget – once it supports create modal) from an Epic that has a Milestone defined, pre-fill that Milestone for the new child item within the create modal.
    1. User can override the pre-filled value
    2. If the user modifies the Parent in the form to a different Epic, update the form to that Milestone if it has one
    3. If user switches to the full page view, ensure the Milestone selection remains
  2. When creating an item in other flows (global menu, new related item, etc), if a user selects an Epic as a Parent attribute and that Epic has a Milestone assigned, update the Milestone for the new item in the form to the associated Milestone for that Parent.
    1. User can override the automated Milestone value
    2. If the user modifies the Parent in the form to a different Epic, update the form to that Milestone if it has one
    3. If user switches to the full page view, ensure the Milestone selection remains

Handling changing type (promoting to epic)

  1. When changing an item type (or promoting) to an Epic, Milestone is now a supported field and should not show a warning anymore that the field is not present/available.
    1. However, if the value is not supported for the Epic (ex: it is a project Milestone), display a warning that the value is not supported in the new namespace (as currently changing type to Epic will move the item to the group level). This warning, which is similar to the planned behavior of the Move action, would be separate from any warnings about fields not being present/available for the item being promoted (see design).

Milestone Report page

  1. Replace the use of the "Issues" label across the report page
    1. Update the "Display by" button labels to be Count and Weight
    2. On the Count display mode:
      1. Update the left legend on the two charts to use Work items instead of Issues
      2. On the Burnup chart, update the popover content to say [X] total [Y] completed (each on their own line like today)
    3. On the Weight display mode:
      1. On the Burndown chart, update the popover content to say [N] remaining weight
      2. On the Burnup chart, update the popover content to say [X] total [Y] completed (each on their own line like today)
    4. Update the "Issues" Tab (below the charts) to be Work items
    5. Update the alert under the Issues Tab (present when over 500 items) to: Showing 500 of [N] items. View all
    6. On the list headers (under the "Issues" Tab):
      1. Remove the term "Issues" from each of the lists
      2. Move the description of the lists (ex: "open and unassigned") to a new line under the list heading, and use gl-font-sm and gl-text-subtle (small, gray text)
      3. Use the work item icon instead of the issues icon (in progress – gitlab-svgs#438 (moved))
    7. On the sidebar of the report page:
      1. Update "Issues" (section under due date) to be Work items
      2. Update "Total issue weight" to be Total weight
  2. Update report so that Epic work items are now being included in metrics / data.
    1. Charts (burndown, burnup)
    2. Sidebar "Issues" (now "Work items") count
    3. "Issues" (now "Work items") Tab and data
      1. Count in the Tab should now include Epic work items.
      2. Add the Type icon to items within the Lists, to differentiate work item types (see design)
      3. List header should now include Epics in the count next to work item icon

Follow-up Criteria (not required for MVC)

ℹ️ Note: if the effort on any of these is low and we can easily include them in the MVC we will do so.

Epic Lists

  1. Users should be able to sort the List by Milestone due date.
  2. If/when we add sort by Priority (#205149), it should take into account Epic milestones.
  3. Milestone should be added as an available bulk action from the list.

Epic Boards

  1. Users should be able to scope a board by a Milestone option.

Epic Detail

  1. Users should be able to leverage quick actions to assign and remove Milestone values.
  2. Quick actions which copy/utilize Milestone data (ex: clone, copy metadata) should now take into account Milestones on Epics (not currently available for Epics but should be considered as that functionality is made available for work items).

Roadmap (deferred due to dependencies discussed here)

  1. Milestone values should be displayed on Roadmap items.
  2. Determine whether any logic needs changed for how we handle the Milestone filter on Roadmaps (I believe we currently look at child item milestones to determine what is shown, where now we need to also account for Epics themselves).

Improved Timebox Inheritance & Syncing

This will be handled separately in #367460.

Edited by Nick Brandt