# Summary In this epic, we will build the relationship architecture for work items. Relationships in this sense apply to parent, child, related, blocked, blocking, other(?) between work items. ## Relationship rules for work item records * Cross hierarchy linking should be available for all relationships within work items * Work items can only have one kind of relationship to another (parent/child, blocking/blocked by/related). * You can easily switch the relationship type without removing and then re-adding the work items to create the relationship. * Work items can only have one immediate parent record * Enforce a strict hierarchy in order to adhere to frameworks like SAFe * Provide a way for customers to model the rules for parent/child relationships. * Example: Epic -\> Feature -\> Story -\> Bug. In this example, you could not have an Epic be the parent of a Bug. * Provide out of the box hierarchies that adhere to industry-standard frameworks * Allow customers to set their own hierarchies * Beyond the restrictions in the restrictions table, work items can have relationships to any other work item in a hierarchy, so long as there is only one type of relationship between two distinct records. * Epic nesting should allow for 9 levels to match OKR nesting (this is an increase from 7 levels which are available in issuables today) ## Relationship management exploration In https://gitlab.com/groups/gitlab-org/-/epics/9083 and https://gitlab.com/gitlab-org/ux-research/-/issues/2168, we are conducting research on the ways that users are thinking about and interacting with relationships in order to create an efficient and pleasant user experience for relationship management in work items. ## Relationship management feature expectations * Display metadata related to the record type (label, milestone, weight, assignee, progress, etc) * Display nested records with collapse/expand controls * Offer expand all / collapse all controls (pending performance impact see [discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/386416#note_1325273564 "OKR MVC - User feedback")) * Allow users to drag and drop to reorder or reparent the records and allow that manual order to remain sticky * Allow users to reparent records without opening another page/tab/modal * Create sort controls for the entire widget (sort by date created, assignee, milestone, etc) * Allow users to edit metadata displayed on the record without opening another page/tab/modal * Ensure users can quickly gauge health status of records (on track, at risk, needs attention) * Ensure users can quickly understand dependencies of records * Ensure users can quickly understand status of records (open, closed, blocked, complete, etc) ## Allowable relationships between issuables and work items In https://gitlab.com/groups/gitlab-org/-/epics/10851 we are creating the ability to have a work item `parent` related to an issuables `child`. Since migration to the work items framework will not occur for all issuable types simultaneously, we will need to support these hybrid relationships until all issuables have been migrated to work items. Below lists the approved mixed relationships between work items and issuables during this transition period: - :white_check_mark: `work item:Epic` can be a parent of an `issuable:Issue` - :white_check_mark: `issuable:Issue` can be a parent of a `work item:task` ## Allowable work item relationships #### Parent:Child | | Epic as child | Issue as child | Task as child | Objective as child | Key Result as child | |--|---------------|----------------|---------------|--------------------|---------------------| | Epic as parent | :white_check_mark: | :white_check_mark: | :x: | :x: | :x: | | Issue as parent | :x: | :x: | :white_check_mark: | :x: | :x: | | Task as parent | :x: | :x: | :x: | :x: | :x: | | Objective as parent | :x: | :x: | :x: | :white_check_mark: | :white_check_mark: | | Key Results as parent | :x: | :x: | :x: | :x: | :x: | #### Linked (blocked by) | | Epic | Issue | Task | Objective | Key Result | |--|------|-------|------|-----------|------------| | Epic blocked by | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | | Issue blocked by | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | | Task blocked by | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | :x: | | Objective blocked by | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | Key Result blocked by | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | #### Linked (blocking) | | Epic | Issue | Task | Objective | Key Result | |--|------|-------|------|-----------|------------| | Epic blocks | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | Issue blocks | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | Task blocks | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | Objective blocks | :x: | :x: | :x: | :white_check_mark: | :white_check_mark: | | Key Result blocks | :x: | :x: | :x: | :white_check_mark: | :white_check_mark: | #### Linked (related) | | Epic | Issue | Task | Objective | Key Result | |--|------|-------|------|-----------|------------| | Epic related to | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | Issue related to | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | Task related to | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | Objective related to | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | | Key Result related to | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |