Follow up "Approval and WIP MR visualization could be confusing #36487" Design + exploration

Problem

The merge request widget supports multiple work flows by nature. However the problem is that as a user there is no clear way to interpret this in order to quickly digest the information you are interested in.

Currently the merge request widget handles all workflows equally (as there is no way of knowing which workflow a user may be interested in), so none stand out. This isn't the complete problem, but it creates a bland pile of information which is not very accessible.

The workflows mentioned are:

• Status of Code (or Status of CI, or Status of Pipeline, Code Quality)
• Status of Review (Approvals, unresolved discussions)
• Merge button (+ reasons it can't be merged)
• Status of Shipment (staging/production deploy, including metrics)

Proposal

Make it so anyone following one of those flows has only one place to look. Yes, the other statuses will be competing, but at least their reasons are clear, so you can quickly determine which to focus on and which to ignore. Memory will make this even better.

• Create distinct hubs of information
  • Think of uniquely branding each hub/service/test
• Introduce a clear hierarchy system
• Better consistent button locations
  • This can greatly help mobile viewports as well
• Overall status of the MR widget should be available at a glance, similar as spotting where a problem is if there is one (Status icons should indicate status in general terms, not be tied to a certain test/ci services)

A wireframe here to illustrate the above points:

Value

This issue should introduce an improved merge request widget design system, which is easily expandable due to correct packaging of already existing information. No new features should be introduced, rather a restructuring of existing data and UI.

mentioned in issue #36487

changed the description

@sarrahvesselov @victorwu @markpundsack as discussed here is the follow up issue on https://gitlab.com/gitlab-org/gitlab-ce/issues/36487.

Please see if the issue makes sense and if you would like to see some edits as to what needs to happen exactly.

Make it so anyone following one of those flows has only one place to look. Yes, the other statuses will be competing, but at least their reasons are clear, so you can quickly determine which to focus on and which to ignore. Memory will make this even better.

A nice bit on this from http://inclusivedesignprinciples.org/#prioritise-content

Prioritise content

Help users focus on core tasks, features, and information by prioritising them within the content and layout.

Full description

Interfaces can be difficult to understand when core features are not clearly exposed and prioritised. A site or application may provide lots of information and functionality, but people should be able to focus on one thing at a time. Identify the core purpose of the interface, and then the content and features needed to fulfill that purpose.

Examples

• Keep task focused: Progressively reveal features and content when needed, not all in one go. Prioritising tasks: An email application is principally for writing and reading email. The "compose" button is, therefore, present on all screens, and early in the focus order. The inbox is prioritised over other lists of email, such as "sent" and "spam" messages. Less used features such as tagging or organizing email into folders appear later in the focus order, as they will generally only be used when the primary task of reading the email is complete.
• Prioritising content: The primary content on a news article page is the story, therefore it should come before other content, both visually and in the source order. Related content, such as similar articles, should follow it, and unrelated content after that.
• Prioritising editorial: Editorial for links, headings and buttons should use plain language and put the primary text first. This applies to both visible and hidden text. This makes the text easy to scan both visually and audibly for screen reader users. Plain language also benefits non native speakers and is easier to translate.

Something like this might be useful for the unique branding and error message hierarchy:

marked this issue as related to #36487

marked this issue as related to ux-research#21

mentioned in issue ux-research#21

Going to rewrite issue, new direction

assigned to @dimitrieh

Talked extensively with @dimitrieh live, so to summarize:

• I'm not sure the second paragraph is an accurate representation of the problem, but the first paragraph is fine.

• Maybe those four workflows are actually a single workflow, with 4 stages, potentially with 4 different people for each stage.

• Today, a lot of our workflows aren't fully covered by existing functionality. So we need to be flexible and let people move between stages. e.g. CI pipeline could fail, but we let you approve and merge anyway. Or all approvers have approved, but we're still waiting on someone else to comment on a specific question.

• For an iterative proposal:

  • Start with the 4 stages and make them hubs of information with roughly equal weight
  • Collapse complete stages, expand the one stage that is active
  • Improve product features so that each stage more properly encompasses the workflow.

Some product improvements:

• If a developer knows that a CI failure is fine, mark it as ignored so the Status of Code section is complete (rather than pushing that to the Merge section where the merger knows to ignore the CI status).
• Put the review app into the Review section, including links to changed pages.
• Make it easy to add specific reviewers, like "@foo can you review this?" and it turns into an official Approval button.
• Make it possible/easy to turn non-code comments into resolvable discussions.
• After merge, show the post-merge commit pipeline in the Status of Shipment section.
• Show that it will deploy to production
• If a MR is reverted, show that below (https://gitlab.com/gitlab-org/gitlab-ce/issues/13997)

mentioned in issue #13997 (moved)

Also:

• Check/X isn't really the right semantics for most of these. Some states are just uncompleted tasks, so I think of an open checkbox instead. But for the Merge state, it feels like the button being disabled or enabled is enough reflection of the state. If an icon really is needed, then I think more in terms of something indicating blocked, like a grayed out open checkbox. e.g. a task that you can't complete yet. Then the left-column of icons feels more like a checklist as you work through a flow.

• Agreeing with https://gitlab.com/gitlab-org/gitlab-ce/issues/13997#note_39271700, if a MR is reverted, that doesn't feel like any of the above states.

• Overall status of the MR widget should be expanded: closed/open/merged just isn't granular enough.

• Each stage should standalone, with all the information needed to understand and act in that stage. e.g. if I'm trying to merge the MR, but it's blocked because CI isn't finished, having note stating that right by the Merge button is much better than making them deduce the reason from the stages above.

added Discussion ~13921 labels

marked this issue as related to #37521

added UX label

mentioned in issue #4176 (moved)

First concept which also grabs ideas from this issue:

@markpundsack this a first rough look at what i had in mind. wdyt?

Also please check the items required for each state.

We will of course need a way to change state for the MR.. so the mr opens up in that stage by default.

marked this issue as related to #29764 (moved)