## Problem - Epics, Issues, and Requirements all have similar but just subtle enough differences in common interactions that it requires the user to hold a complicated mental model of how each behaves. - Using labels to denote Issue types is cumbersome and makes every reporting view more complex (because you have to include all labels in picking which you want to show analytics for). - [Issue Types](https://app.periscopedata.com/app/gitlab/654183/Plan-stage-.com-events) are one of the top two use cases of labels. Given that, we should provide first-class support for it. - Issues are starting to feel cluttered as we add more and more capabilities to them. There is no consistent pattern for how to surface relationships to other objects, there is not a coherent interaction model across Issuables, and the various implementations of [issue types](https://docs.gitlab.com/ee/development/issue_types.html) are feeling the pain of the lack of flexibility and extensibility. ## Solution * We cannot re-use our existing Issues since the architecture is not flexible and scalable enough to accommodate all the features needed for our future vision. * We are also taking this opportunity to change terminology from being centered around "Issues" to "Work Items". The term "Issues" is not comprehensive enough for all the capabilities we plan to build in the future. * We will start this effort by creating a new work item called **Tasks**. This was a long-standing ask that provides net new customer value. Starting with a new item also reduces the risk of changing an existing capability like Issues, which has significant traffic and is part of key customer workflows today. * We will build capabilities in the new Work Items framework until we have reached parity with Epics and Issues. Then we will migrate them to use Work Items. * Create a new architecture called Work Items that will support Issues, Epics, Requirements, and future planning items. This will allow us to enhance the experience for Epics and Requirements and expose more functionality that is available in Issues to them. ### Roadmap By Product Group See [this spreadsheet](https://docs.google.com/spreadsheets/d/1D3QZ5L2hb7yzIyYnob13o3Mk2vxzCplR-hc5GFmr38c/edit#gid=0) for a breakdown of work and how it aligns with each objective ### Important Links - https://gitlab.com/gitlab-org/gitlab/-/issues/368044+ - https://gitlab.com/gitlab-org/gitlab/-/issues/368607+ ### Q & A <details> <summary>If we were to move mutli-level epics to premium and add the ability to use epics in projects, what do users get from tasks that is not already available?</summary> In terms of customer value, [this video](https://www.youtube.com/watch?v=g5n0dEwcXio&feature=youtu.be) explains "why" fairly succinctly. In terms of "why" from a technical and product perspective, the main point is that we do not want to maintain two different objects -- issue and epic -- in the long run. To advance the maturity of epics, they need: * Assignees * weight * first-class types * Design manager * The ability to be moved to other groups * Description templates * integrated with webhooks * integrated with events so activity shows on a user's profile. * ...the list goes on On top of that, based on our longer-term vision: * It will be even more work to integrate epics into places like values stream analytics. * The two frontends for issues and epics are different code, so whenever we want to change one aspect of issues or epics that share functionality (say updating the labels widget to pajamas), we have to do it twice. It will require duplicate work for any new things we introduce like https://gitlab.com/groups/gitlab-org/-/epics/5099+ * The date inheritance model on epics is fairly broken. * Issues need to be included in roadmaps. So...we can do one of the following: 1. Spend the time doing all the work to bring epics up to "parity" with issues, and then double the effort for every change moving forward. This is compounded with each new first-class object we introduce (ex: all the same things noted above for epics apply to requirements). This would also entail making both Epics available in Projects and Issues available in Groups (twice the work). 2. Consolidate the objects down to a single object, fix some of the underlying wonky stuff (date inheritance model) as we go, and only migrate one object to Group or Project. Path 2 requires less effort and ultimately increases the rate at which we can improve the maturity of the JTBD for which epics are currently being used. </details> <details> <summary>Why did you decide to start with Tasks?</summary> In terms of customer value, [this video](https://www.youtube.com/watch?v=g5n0dEwcXio&feature=youtu.be) explains "why" fairly succinctly. Additionally, <span dir="">\~</span>6% of Plan users currently have access to the notion of a grandparent (multi-level epic). <span dir="">\~</span>15% have access to the notion of a parent (single-level epic). 79% have no notion of parenting in their workflows. By introducing Tasks, we are providing <span dir="">\~</span>21% of Plan users with the notion of grandparents, and 79% of Plan users with the notion of parent/child relationships. From a technical and product perspective, we needed to find a real problem to solve that would allow us to: 1) Build the work items API, 2) Design and build a new frontend, 3) Incrementally work towards migrating epics to work items -- which requires that we add "parent/child" relationships to issues. 4) low risk to disrupting existing issue workflows 5) Reduce the risk for reaching eventual consistency that allowed us to iterate and get feedback as we work towards migrating various objects to be a "work item" </details> ## Widget availability by work item type <details> <summary>Click to view widget availability by work item type as of 2023-10-26</summary> | Widget | Description | ¹Epic | Issue | Task | Objective | Key Result | |--------|-------------|-------|-------|------|-----------|------------| | WorkItemWidgetAssignees | List of work item assignees | :white_check_mark: | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetAwardEmoji | Emoji reactions added to work item, including support for upvote/downvote counts | :white_check_mark: | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetCurrentUserTodos | User todo state of work item | :white_check_mark: | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetDescription | Description of work item, including support for edited state, timestamp, and author | :white_check_mark: | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetHealthStatus | Health status assignment support for work item | :white_check_mark: | :heavy_check_mark: | :question: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetHierarchy | Hierarchy of work items, including support for boolean representing presence of children. | :heavy_check_mark: | :heavy_check_mark: | :x: | :white_check_mark: | :x: | | WorkItemWidgetIteration | Iteration assignment support for work item | :x: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: | | WorkItemWidgetLabels | List of labels added to work items, including support for checking whether scoped labels are supported | :white_check_mark: | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetLinkedItems | List of work items added as related to a given work item, with possible relationship types being relates_to, blocks, and blocked_by. Includes support for individual counts of blocked status, blocked by, blocking, and related to. | :heavy_check_mark: | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetMilestone | Milestone assignment support for work item | :question:² | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :x: | | WorkItemWidgetNotes | List of discussions within a work item | :white_check_mark: | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetNotifications | Notifications subscription status of a work item for current user | :white_check_mark: | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetProgress | Progress value of a work item. | :question: | :question: | :question: | :white_check_mark: | :white_check_mark: | | WorkItemWidgetStartAndDueDate | Set start and due dates for a work item | :heavy_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: | | WorkItemWidgetStatus | Status of a work item when type is Requirement, with possible status types being unverified, satisfied, or failed | :question: | :question: | :question: | :question: | :question: | | WorkItemWidgetTestReports | Test reports associated with a work item | :x: | :x: | :x: | :x: | :x: | | WorkItemWidgetWeight | Set weight of a work item | :question:² | :heavy_check_mark: | :white_check_mark: | :x: | :x: | ###### Legend - ¹Epic widget availability based on widgets found in https://gitlab.com/groups/gitlab-org/plan-stage/-/work_items/27 - :heavy_check_mark: Widget should be available - :white_check_mark: Widget is currently available - :x: Widget should not be available - :question: Widget not currently available - do we want it on this type? - :question:² Widget not currently available - we want some form of this widget on the record, but there may be a nonstandard implementation as compared to the other work item types. Widget definitions in code: https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/work_items/widget_definition.rb?ref_type=heads#L17 </details>