Unifying the Commit/MR/Pipeline/Build and Issue Views

This will be a meta issue to oversee our work on improving and unifying all the different views from Commits/Merge Requests/Pipelines/Builds and Issues.

The goal of this issue is to:

Decide on a unified structure for those views to cohere to.
To add useful context in all views.
To refine all elements visually and responsively.
Setup a plan of actionable issues to tackle.

This issue is a continuation and extension from a discussion at https://gitlab.com/gitlab-org/gitlab-ce/issues/20892#note_15174692

To make an example of the current situation: The Commit view is currently quite different from the Merge Request view. There is less sensible styling and the information hierarchy suffers as a result from it. We continue to add information but run out of a way to apply these features visually in a way that makes sense.

Unified Structure

In short we have to decide on a unified structure:

From the discussion at https://gitlab.com/gitlab-org/gitlab-ce/issues/20892#note_15174692 I have come to the conclusion that the Merge Request view has the most extendible format for all kinds of information types.

Say we look at an existing Merge Request: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6935

General Structure wise this looks like:

Or to lay them on top of each other:

We can then begin to discuss what each information section should actually include.

We are leaving out the "Top Bar" and "First Level Navigation" as these are cross view/page elements

That leaves us with:

Title Bar
Description
- Description Modified Time
System Information
Tab Navigation
- Tab Content
Sidebar

Title bar

If we look at the titlebar we can clearly point out several purposes:

Tell us which what type of view we are looking at
Tell us the status of that view (if it has any)
It gives us a uniquely Identifiable ID through a certain string of characters (related to https://gitlab.com/gitlab-org/gitlab-ce/issues/22148)
It gives us context when this view was created (this becomes important later on at the build view)
Who was responsible for creating it
It gives us a place for our most prominent/most used actions/buttons

This is basically the essential information that is needed in this section... if we look at for example a "build" page, we can see that it has some other things in there that try to provide extra context. This is currently all put in the titlebar as there is no format where to put this properly.

This becomes even more apparent when looking at small viewport widths:

Description

Description is pretty straight forward, but does need some improvements in the sense of hierarchy, which will be mentioned later on.

Also some of the views do not have or need a description, examples being the build page. The commit view and Pipeline view actually have a description if its in the commit message. The question here is if the pipeline should include this "commit information" as well?

A closer look at the build page reveals this information in the sidebar: image. This is a good example on probable inconsistencies across views as well.

Purposes are:

What is it about in one short sentence, aka the title.
What is it really about? Description text
Description Modified Time: When was this description last edited/modified? Or to make it more general: automatic generated information about this section specifically

Again this is basically all there needs to be, except for perhaps a way of looking through all the edit versions: #22162 (closed) & #4199 (moved) . Which I would probably place on the same line as the "Description Modified Time".

System Information

This is the most interesting part of the structure discussion, along with the sidebar. These places are the ones where misc information is shown or where context information can be added.

Currently only the "Merge Request" page has a proper "system information" element. This shows us information such as related pipelines, If its ready to merge, if it closes a related issue, etc. Within the vicinity of all this context related information it also provides a way to act upon it to merge it. The Merge Request is unique in this case as it is the only view that has a context related actionable item.

The way it however visually displays the information creates a clear visual hierarchy.

Purposes:

Provide context or extra system generated information.
Adds additional or extra important actionable items to the view.

Currently it looks like:

As for pure general structure we have the following:

Primary buttons that represent the final and most important action on this page (Note: Not the most frequently used, which are in the titlebar!)
Buttons that spawn additional elements such as modals/pop-ups/dropdowns (can only be for a whole row with title, not line specific)
In-line links that open up new screens (only on a textline, and in context of)
Additional links that open up new screens (only on a textline, and in context of)
Section dividers (rows)

IMO this misses one thing, which is internal structure. A way to group similar messages instead of unilaterally creating new rows for each kind of information:

Title(s)

We need a title to group similar messages and create a consistent look which can be used in multiple views:

Sidebar

The sidebar is a special element that some pages have and others don't.

Purposes:

It shows (editable) information and actionable items that have an effect elsewhere in the application or are connected to profiles.

Examples of this are for example to be able to subscribe to an issue or MR, to apply labels or to assign someone.

Currently the issue view and merge request view have almost identical sidebars. The only other view that currently has a sidebar is the build view. It seems to me that the purpose of the sidebar in the build view has an entirely different reason.

It shows no information that is editable or actionable which has an effect somewhere else in the application. The reason here has been IMO to move up the build log and just place all other information in the sidebar. The question here is, are we oke with the build view being an exception? It of course has no way of holding similar information to the MR and Issue view. And it brings up several other questions:

With the introduction of https://gitlab.com/gitlab-org/gitlab-ce/issues/23205#note_16806248 and my older mockups at https://gitlab.com/gitlab-org/gitlab-ce/issues/20892#note_15174692 we will have a mixed state of elements that cover the same ground... How will we differentiate? Do we really need the sidebar? Do we want a sidebar at the pipeline & commit views? Or do we want all extra/context related/system generated information in the sidebar in these views? The point here is: there is limited space there and not all information is equally able to fit in such small widths. Would it be a bad thing to move down the build log to show additional information first?

An additional functionality to the sidebar is that is can be collapsed. Currently the sidebar at the build view behaves differently than the others. Meaning that a user cannot collapse the sidebar unless he/she is on a small width viewport. https://gitlab.com/gitlab-org/gitlab-ce/issues/23298 wants to make this functionality available in the build view too.

Point here is, when a sidebar is collapsed it should have a smaller "collapsed" state, like in the issue view. We should take this into account if we'd create additional sidebars.

I left out the parts of the build view sidebar that make no real sense at the moment.

For example the "subscribe button" in the issue/mr sidebar should actually behave just like the "todo" button, something like:

and

The "raw" and "erase" buttons are styled similarly, but actually make no sense in the way they are placed...

Erase should probably be in the titlebar, as it has a severe effect on the page just like close an issue (more permanent though)

Raw gives a raw output of the build log in a new tab.. this should be shown in the build log element/section instead of the sidebar, where it seems out of place....

Perhaps these buttons can both be seen as similar buttons as the merge and revert buttons in the merge request view and therefore be placed similarly, but not in the title bar.

The last thing that is left there is the "retry" button which should obviously be placed in the titlebar as its the most frequently used: https://gitlab.com/gitlab-org/gitlab-ce/issues/23273#note_17030857

Sidenote here: In the Issue and MR view there is a "references" section in the sidebar.. should this even be in there...

Opinion: I think the sidebar at the build page should consist purely out of the pipeline builds list

Tabs

Lastly we have the tabs section. There are some peculiarities here in between views.

Purpose:

Show different kinds of information within the same page without overcrowding
Show information that is not context but actually part of...

The different tabs we currently have across page are:

View	Merge Request	Issue	Commit	Pipeline	Build
Does it have discussion?	yes	yes	yes	no	no?
Discussion Tab	yes	no/yes (1 tab only)	no	no	no
Does it include commits?	yes	no	no	no	no
Commits Tab	yes	no	no	no	no
Does it include Pipelines?	yes	no	yes	no (pipeline graph)	no
Pipelines Tab	yes	no	yes	no	yes (sidebar)
Does it include Builds ?	no	no	yes?	yes	no (build log)
Builds Tab	yes	no	yes?	no	no
Does it include Changes?	yes	no	yes	no	no
Changes Tab	yes	no	yes	no	no

The peculiarities here are:

Merge request page does have a builds tab... while builds are part of a pipeline... one level below
Commit page have discussion, but have no discussion tab
Commit page does have a builds tab... while builds are part of a pipeline... one level below
Pipeline page should have tabs: "Pipeline graph" and "Builds"
Build page should IMO have the ability for discussion, like diffs. To point/discuss parts where the build has failed. These discussions should be able to be resolved and perhaps show up in MR discussions like diffs
With the discussion tab come the award emoji... this is up for discussion if these should be there for commits and/or builds
An improvement we could think about in the future is using tabs in the issue page, to have a page for "designs" or media related to #2641 (closed)

Context

The system information element and the sidebar (in the case of the build page) can be used for adding context. Currently all views give some sort of context but do so in unexpected ways/places or are generally inconsistent.

An example, would be that related/mentioned merge requests in Issues are vastly different from related pipelines in a Merge request. Another would be the mentioning of context in the titlebar of a build view, while this is not consistent with the pipeline view etc. Also as we have discussed before, the title bar is not the place where this information should be present.

Currently the context information we can provide across views are:

Source Branch Name
Source Branch URL
Source Branch removed status?
"Merge into" Branch Name
"Merge into" Branch URL
Commit ID
Commit Status (is there such a thing based on the latest pipeline??)
Commit URL
Commit Title
Amount Commits behind "Merge into" Branch
Amount of Parent commits
Parent commit ID
Parent commit URL
Parent commit Branches
Parent commit Branches URL's
Merge Request ID
Merge Request URL
Merge Request Name
Merge Request Status
Merge Request Last Pipeline Status
Pipeline ID
Pipeline URL
Pipeline Status
Pipeline Start Time
Pipeline Finish Time
Pipeline Duration
Pipeline Queue Duration
Amount of builds in Pipeline
Pipeline Stage Name
Build ID
Build Name
Build URL
Build Status
Build Start Time
Build Finish Time
Build Duration
Deployment Environment Name
Deployment ID
Deployment Time
Deployment URL
Issue Name
Issue ID
Issue URL
Issue Status
Triggerer Name
Triggerer Profile URL
Triggerer Avatar
Triggerer Handle
Trigger Time
Author Name
Author Profile URL
Author Avatar
Author Handle
Author Time
Merger Name
Merger Profile URL
Merger Avatar
Merger Handle
Merge Time
Approver Name
Approver Profile URL
Approver Avatar
Approver Handle
Approve time
Runner ID

We should define exactly which context we should provide in each view:

I will mark the item bold which are not yet there!

Issue

Issue Name
Issue ID
Issue Status
Author Name
Author Profile URL
Author Avatar
Author Handle (tooltip)
Author Time
Related Merge Request ID
Related Merge Request URL
Related Merge Request Status
Related Merge Request Last Pipeline Status
Related Merge Request Name

Merge Request

Merge Request ID
Merge Request Name
Merge Request Status
Author Name
Author Profile URL
Author Avatar
Author Handle (tooltip)
Author Time
Source Branch Name
Source Branch URL
Source Branch removed status?
"Merge into" Branch Name
"Merge into" Branch URL
Latest Pipeline Status
Latest Pipeline ID
Latest Pipeline URL
Latest Pipeline Finish Time
Latest Pipeline Duration
Latest Commit ID
Latest Commit URL
Merger Name
Merger Profile URL
Merger Avatar
Merger Handle (no tooltip atm)
Merge Time
Approver Name
Approver Profile URL
Approver Avatar
Approver Handle (no tooltip atm)
Approve time
Amount Commits behind Merge into Branch
Deployment Environment Name
Deployment URL
Deployment Time

Commit

Author Name
Author Profile URL (currently displays Author email?!?)
Author Avatar
Author Handle (should be in the tooltip)
Author Time
Commit ID
Commit Name
Commit Description
Commit URL (Is in there, but shouldn't be.. you are already on that page)
Latest Pipeline Status
Latest Pipeline ID (Question here is.. do we only want to show the latest pipeline)
Latest Pipeline URL
Latest Pipeline Finish Time
Latest Pipeline Duration
Deployment Environment Name (Question: Do we want to show deployment environments here as well?)
Deployment URL
Deployment Time
Related Merge Request ID (The question here is, as a commit can be part of a pipeline.. instead of just being related.. if it should have a "MR" tab instead of just being inside the system information context element)
Related Merge Request URL
Related Merge Request Status
Related Merge Request Last Pipeline Status
Related Merge Request Name
Amount of Parent commits
Parent commit ID
Parent commit URL
(Parent commit) Branches
(Parent commit) Branches URL's

Pipeline

Pipeline ID
Pipeline URL (shouldn't be there, you are already on that page)
Pipeline Status
Pipeline Finish Time
Pipeline Duration
Pipeline Queue Duration
Amount of builds in Pipeline
Commit Name
Commit Name URL (this link is broken and should have the commit ID URL, plus an icon to indicate that this is a commit title, not a branch title!)
Commit ID
Commit ID URL
Author Name (The question here is if the author should be/is the triggerer.. as a pipeline cannot have an author)
Author Profile URL (currently displays Author email?!?)
Author Avatar
Author Handle (should be in the tooltip)
Author Time
Triggerer Name
Triggerer Profile URL
Triggerer Avatar
Triggerer Handle (should be in the tooltip)
Trigger Time
Source Branch Name
Source Branch URL
Merge Request ID (if it is triggered in the context a MR!)
Merge Request URL
Merge Request Status (do we need to see if it is open/closed/merged? )
Merge Request Last Pipeline Status (As we are looking at one of the pipelines of this merge request... is it important to see if the latest pipeline of that MR has passed yes or no?)
Merge Request Name (perhaps in tooltip)

Build

Build ID
Build Name (this is currently only displayed in the sidebar.. in the stages/build list)
Commit Name (Currently displayed in the sidebar)
Commit ID
Commit ID URL
Commit Name URL (this link is broken and should have the commit ID URL, plus an icon to indicate that this is a commit title, not a branch title!)
Pipeline ID (currently no way of knowing which pipeline ID this belongs to)
Pipeline URL
Pipeline Status (Do we want to show overall pipeline Status?)
Pipeline Finish Time
Pipeline Duration
Author Handle (The question here is if the author should be/is the triggerer.. as a build cannot have an author)
Author Name (Currently not available...should be the other way around with Handle in tooltip)
Author Profile URL
Author Avatar
Author Time
Triggerer Name
Triggerer Profile URL
Triggerer Avatar
Triggerer Handle (should be in the tooltip)
Trigger Time
Source Branch Name
Source Branch URL
Merge Request ID (if it is triggered in the context a MR! Currently displayed in the sidebar)
Merge Request URL
Merge Request Status (do we need to see if it is open/closed/merged? )
Merge Request Last Pipeline Status (As we are looking at one of the pipelines of this merge request... is it important to see if the latest pipeline of that MR has passed yes or no?)
Merge Request Name (perhaps in tooltip)
Runner ID (currently in sidebar)
Pipeline Stage Name (currently only visible in the sidebar through build list)

All in all, we have a lot to improve upon the commit/pipeline and build pages

Visual and Responsive Refinements

This part is going to be filled in later on, when all the previous questions have been answered.

With the things mentioned above, we should automatically get a better styled unified structure across these pages, which will act better responsively as well. This for example because of the titlebar being shortened to its bare essentials, giving less problems in smaller view ports!

However speaking about the titlebar:

https://gitlab.com/gitlab-org/gitlab-ce/issues/22518#note_16734201 speaks about the "about" part in the time relation element. We should look for ways to shorten or truncate the information even more for smaller viewports..

Places where we can improve there:

human time notation: "3 months ago" to perhaps "2016/06/14".. see if this is nessecary, also: https://gitlab.com/gitlab-org/gitlab-ce/issues/22518#note_16734201
Merge Request.. could be changed into "Merge Req" or even "MR", learning users to see MR as Merge Request (yes I am aware of the conversation against this)
Pipeline status icons.. should be changed to just the icon.. like Merged/Open/Closed.
"Opened", "Authored", "Triggered" could be changed to a different notation with "at" like: MR !12345 at 2016/06/14 by @dimitrieh (with the added context in full view, we may be able to get away with this) possible I am over optimising this.
Options buttons is there even if its just one option.. also.. we should be able to optimise there.. so it doesn't take up a whole row.

Plan of Action

The plan of action will be filled in later on after the questions have been answered

However the first step into this will be to have a first step into the right direction with the commit view

https://gitlab.com/gitlab-org/gitlab-ce/issues/20892#note_17103480

cc: @markpundsack @awhildy @pedroms @tauriedavis @hazelyang @cperessini @pbr

PS: WIP :)

Admin message