Extensible widgets - related and linked items
Problem overview
This issue is to begin exploring possibilities for creating a relationship widget that could be reused across various issuables to provide a more consistent experience for visualizing relationships and interacting with related objects.
Problem statement
- We have lots of ways to define relationships for objects within Issues and Epics. They are all slightly different and some are more polished than others (see MRs vs. Commits - #229731 (comment 399403301)). In order to make Issues, Merge Requests, Epics, Incidents, and any other
Issuable
more lovable, we should create a more consistent user experience for relating objects to one another with as little duplicated technical effort as possible -- even those objects that are not explicitly issues like Feature Flags, Vulnerabilities, and more. - Merge requests are just "related" to an issue. There is no way to 100% determine that an MR implements all or part of an issue. If you mention an issue in ANY MR, it becomes related. We need the ability to specify whether the relationship is "weak" or "strong".
- A lot of the related items are not actionable once they are resolved/closed, but they still take up a prominent amount of real estate (#229731 (comment 399403301))
- Once we have custom issue types, we need a way to allow the end user to define the relationship and hierarchy between their issue types.
Feature discovery checklist:
-
Mural: Create initial problem statement & identify relevant job(s) -
Mural: Capture individual brainstorming ideas for feature -
Mural: Prioritize ideas in a matrix -
Mural: Iterate on problem statement after exercise -
Figma: Create task flow of screens based on ideas broken into Sees and Dos -
Figma: Using atomic design principles, flesh out the See | Do concept -
Figma: Create low-fi wires of possible solutions based on See | Do -
Figma: Outline key interactions such as on hover, on focus, etc. -
Figma: Conduct min 5 usability tests on design once it’s refined enough
Intended users
- Presley if we want to include relating designs to issuables
- Sasha, Devon and Delaney for relating MRs and Commits to an issue
- Sidney and Alex for relating incidents and alerts to Issues and the MRs that resolve them
- Sam for relating security vulnerabilities to the issues that will resolve them and then ultimately the MRs that patch them.
- Rachel for related planned, upcoming release versions to the issues that need to be included in the release -- and ultimately the MRs that implement the issues.
- Parker for relating issues to other similar issues or epics to build out a plan...and then track the progress via related MRs.
- Cameron for being able to easily collect audit reports and enforce compliance controls across objects that are required to have related objects.
JTBD
Coming soon...
Proposal
Create a customizable component for relating work items and defining the relationship type. "Related work items" in GitLab is defined as: tree components which enable the management of relating issuables to one another. The term refers to the following:
- "Linked Issues" on issues (
✅ ) - "Related Merge Requests & Branches" on issues (
✅ ) - "Epics & Issues" on epics (
✅ ) - "Related Incidents" on issues (
✅ ) - "Requirements" on Issues (
✅ ) - "Implementation Issues & MRs" on Requirements (
✅ ) - "Vulnerabilities" on Issues. (
✅ ) - ...and more
Questions
- Is there anything else we would define as a related work item?
- Is the goal - "I want the ability to have related things but not be limited by the type of relationship, instead having the ability to define that relationship."
Diagram / Types of Relationships
graph TB
subgraph ide1 [Planning & Scheduling Hierarchy]
s1[Capability]-->|Decomposed into|s2[Epic]
s2 -->|Decomposed into|s3[Feature]
s3 -->|Decomposed into|s4[User Story]
s3 --> s5[Bug]
end
subgraph ide2 [Long Lived Behavior of Software]
l1[L1 Requirement] -->|Decomposed into|l2[L2 Requirement] -->|Decomposed into|l3[L3 Requirement]
end
subgraph id3 [Quality Management]
t1[Test Session] -->|Has Many| t2[Test Cases]
end
MR -->|Maps code to scheduled implementation|s4
l3 -->|Acceptance Criteria|s4
t2 -->|Steps to verify behavior|l3
Incident -->|Schedule fix|s5
l2 -->|Schedule implementation|s3
Vulnerability -->|Schedule fix|s5
Vulnerability .->|In code related to|l2
MR .->|Maps code to relevant requirement|l3
There are few foundational types of relationships:
- Related - Loose relationship. No hard link. I can link an issue and an MR comment to relate them together even if the MR is not implementing the referenced issue.
- Blocking - Dependent upon one another but not in the same work item tree.
- Parent/Child - Hard link. All children complete / finish parent. This is the "work item tree" similar to multi-level epics + issues + MRs that implement an issue.
- A parent work item in a given work item tree may be the child of another item outside of the current item tree. A good example is a vulnerability. An issue and MR complete / resolve a vulnerability. The issue also has another parent within its own work item tree.
Bigger diagram:
- Dotted lines means the relationship doesn't currently exist in a meaningful way because we haven't build the features out or we haven't done a great job of modeling the relationships.
graph TD
Issue -->|Many|Epic
Issue -->|Many|Milestone -->|This is a broken relationship|Release
Issue -->|Many|Iteration
Issue .->|N/A - Many|Release
Merge_Request -->|Many|Milestone
Merge_Request -->|Many|Release
Merge_Request -->|Many|Issue
Merge_Request .->|N/A - Many|Incident
Merge_Request .->|N/A - Many|Iteration
Vulnerability -->|Many|Merge_Request
Requirement .->|N/A - Many|Issue
Requirement .->|N/A - Many|Epic
Reviewer -->|1-1|Approval
Reviewer .->|N/A - Many|Issue
Assignee -->|Many|Issue
Assignee -->|Many|Merge_Request
Assignee -->|Many|Incident
Assignee .->|N/A - Many|Epic
Approval .->|N/A - Many|Issue
Approval -->|Many|Merge_Request
Test_Case .->|N/A - Many|Requirement
Design .->|N/A|Epic
Design -->|Many|Issue
Design .->|Many|Requirement
Alert .->|N/A - Many|Incident
Incident .->|N/A - Many|Issue
Iteration .->|N/A|Milestone
Branch -->|Many|Issue
Branch -->|1-1|Merge_Request
Milestone -->|Many|Epic
Technical Considerations
Performance Problems
Rendering parent/child relationships that are deeply nested is not very performant right now. It takes 7-10 seconds for the gitlab-org
GraphQL to be returned to the client. Product manager assumption:
- It is slow because we have to query all children to get their milestones, then build up the dates for all sub-epics to eventually get the date range for the top most parent epic.
- When you have hundreds of epics across dozens of subgroups and milestones, this will always be a performance problem.
Alternative Approaches
- Store the date range on any parent issue in the database
- When a child issue's date or timebox changes, automatically propagate the event to the parent issue to trigger an update to the parent issue's data range stored in the database.
- When requesting parent issues to render on a roadmap view, there will not be a need to deeply traverse children to dynamically render the date range during the request/response cycle.