[UX] Work items: Development widget (MRs, branches, feature flags)

Consolidate related MR, branch, and feature flag lists and controls in work items

Background

Today an issue can be linked to MRs, branches, and feature flags. All 3 object types are listed in separate containers, which are separate from "Linked items" and "Tasks" — in total a user could see 5 separate lists of relationships below the description.

Merge requests and branches are related — each of these usually contributes to the execution of an issue or task through code. There is an implicit relationship type of "Implemented by". Branches, in the happy path, become merge requests and thus move across these containers. Users can also create both from an issue, though unlike other relationships the creation control is separate from the list.

In some cases however Merge Requests are simply linked to an issue — such as when a user references an MR from an issue comment. This represents a "Related", rather than "Implemented by", relationship but appears alongside other MRs, diluting the clarity of whether this issue is being resolved. As an example a comment noting a change to a UI component being used as an FYI will appear next to the MR using that component to resolve the issue despite having very different implications for the issue.

Feature flags can only be linked from the feature flag detail page. While this is presented today as a 'related' relationship, these tie to the implementation of an issue or task (see discussion)

"Implemented by" is similar to a "parent of" relationship — in both cases the completion of each item may represent the delivery of this item. The actual impact of the relationship however is different. While a parent/child relationships relate plan objects to other plan objects and show how an item is broken down into parts for planning, with inheritance or rollups between them, implementation relationships relate plan objects to code-related objects and today do not have any sort of inheritance or rollup beyond closing on merge.

Proposal

🖱️ Prototype

📼 Video walkthrough on Youtube (15m) | Skip to flow walkthrough

Establish a "Development" widget containing merge requests and branches
Branches, MRs, and FFs that are directly linked to an issue, such as through creation from the issue or matching a closing pattern, would appear together in a single section. If an MR is created for a branch, the branch would be replaced by the MR; it's position in the list may move but it would remain in the same list. As currently proposed, this widget is presented differently from other relationships — while 'child' and 'linked' widgets are shown in the body, the Development widget is in the sidebar. This ties this work on the item close to labels (as a proxy for status, which might reflect this being "in development" or "in review" based on MRs in the list), time tracking (which might be based on work on an MR), and health status, which may be dependent on the workflow of an implementing MR, as well as assignee which in many cases will be the developer working on the issue. In the empty state users are presented with actions to create an MR or branch; in all states users can create or link items from the "+" dropdown, which will open the form in a modal. Benefits For any issue or task resulting in an MR, provides an SSOT for all work on implementing a solution, rather than having to look in multiple places. Anchors the creation action and allows created items to appear in the same space; today this action is in the middle of the page and not connected to the list. Users can easily see if there is work on this and either explore that work or start their own. Risks Sidebar placement may be "below the fold" in some cases, especially if many labels are present. This is also true of the current layout but based on description length. Placing this action in a more static location at the top would avoid this risk but detach the creation action from the list. By presenting the form in a modal, we could additionally include keyboard shortcuts as well as an action in the Actions menu (kebab) at the top to minimize this risk. The naming of this can change; "Development" is familiar in competitors but "Code" could mirror the navigation section containing MRs and branches.	`See designs for full workflow.`

Establish a "Development" widget containing merge requests and branches

Branches, MRs, and FFs that are directly linked to an issue, such as through creation from the issue or matching a closing pattern, would appear together in a single section. If an MR is created for a branch, the branch would be replaced by the MR; it's position in the list may move but it would remain in the same list.

As currently proposed, this widget is presented differently from other relationships — while 'child' and 'linked' widgets are shown in the body, the Development widget is in the sidebar. This ties this work on the item close to labels (as a proxy for status, which might reflect this being "in development" or "in review" based on MRs in the list), time tracking (which might be based on work on an MR), and health status, which may be dependent on the workflow of an implementing MR, as well as assignee which in many cases will be the developer working on the issue.

In the empty state users are presented with actions to create an MR or branch; in all states users can create or link items from the "+" dropdown, which will open the form in a modal.

Benefits

For any issue or task resulting in an MR, provides an SSOT for all work on implementing a solution, rather than having to look in multiple places.
Anchors the creation action and allows created items to appear in the same space; today this action is in the middle of the page and not connected to the list. Users can easily see if there is work on this and either explore that work or start their own.

Risks

Sidebar placement may be "below the fold" in some cases, especially if many labels are present. This is also true of the current layout but based on description length. Placing this action in a more static location at the top would avoid this risk but detach the creation action from the list.
- By presenting the form in a modal, we could additionally include keyboard shortcuts as well as an action in the Actions menu (kebab) at the top to minimize this risk.

The naming of this can change; "Development" is familiar in competitors but "Code" could mirror the navigation section containing MRs and branches.

See designs for full workflow.

Move non-implementing MRs into Linked items > Related
MRs which are only indirectly linked, such as those linked via reference in a comment, would appear in the existing "Linked items" list under "Related". We could later explore whether an MR can be "blocking" or "blocked by" an issue, which would require the ability to create an MR link from the issue itself. Benefits Streamlines relationship widgets; users still can see all related items but if not interested only have to collapse 1 block instead of 3. Shifts to each widget being aligned to the relationship type rather than the object type, where relationship is more meaningful to understanding the issue — how do other items affect this item?

Move non-implementing MRs into Linked items > Related

MRs which are only indirectly linked, such as those linked via reference in a comment, would appear in the existing "Linked items" list under "Related". We could later explore whether an MR can be "blocking" or "blocked by" an issue, which would require the ability to create an MR link from the issue itself.

Benefits

Streamlines relationship widgets; users still can see all related items but if not interested only have to collapse 1 block instead of 3.
Shifts to each widget being aligned to the relationship type rather than the object type, where relationship is more meaningful to understanding the issue — how do other items affect this item?

Solution validation

An earlier concept for a Development widget was tested as part of https://gitlab.com/gitlab-org/ux-research/-/issues/2486, which found (actionable insight - internal only):

For those that found the Development widget in the sidebar, it was well understood that this was where they could add/connect merge request items. However, it wasn’t always obvious to participants and was sometimes missed. Some feedback as why they missed it initially were:

They didn’t see an exposed button for “Create/Add merge request”

The text within the Development widget was small and dialed back (lighter gray)

The term “Development” is something they don’t typically interact with (a PM), so they just glanced over it.

Further testing is needed with the revised widget, with a greater focus on the Sasha persona as the primary user of this feature.

Future consideration

Mirror the "Development" widget on MRs/branches

As the development relationship is bi-directional, the MR could show the issue being implemented in a similar widget. Today this is noted in the description text, e.g. Closes #3. Branches do not indicate any relationship to issues.

Edited Apr 01, 2024 by Nick Leonard