[go: up one dir, main page]

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

  1. 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.
  2. 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".
  3. 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))
  4. 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.
Edited by Gabe Weaver