Skip to content

Better clarity and transparency when comparing branches

Problem

The dropdown for comparision options is not clear about what the difference is with .. and ... in the Compare page.

CleanShot_2022-10-13_at_13.58.42

Proposal

The dot-notation made it confusing to understand what kind of comparison was being performed.

To replace the dot-notation, we will provide radio button options to explain what the comparison would be display:

  • Only incoming changes from source
    • Equivalent to the 3-dot git notation of "git diff A...B". Show changes coming in from B into A.
    • This is the default comparison
  • Include changes to target since source was created
    • Equivalent to the 2-dot git notation of "git diff A..B". Show changes between A and B from last common commit.

To make this happen we will be addressing these four (4) areas:

  1. UI change
  2. Remove dropdown for comparison mode changes
  3. Breadcrumb changes
  4. Change the way "swap revision" works

We are not looking at making any URL changes at this point as it would result in a breaking change to the API #408914 (comment 1374542523).

Current Proposal
image image

UI changes

Remove dropdown for comparison mode changes

  • Remove dropdown of dot notation
  • Introduce a radio option group to control what the comparison will display
    • Legend label: Show changes
    • Option 1: Only incoming changes from source
      • Default selection
      • URL structure: /-/compare?from={SOURCE_BRANCHNAME}&to={TARGET_BRANCHNAME}&from_project_id={SOURCE_PROJECT_ID}
    • Option 2: Include changes to target since source was created
      • URL structure: /-/compare?from={SOURCE_BRANCHNAME}&to={TARGET_BRANCHNAME}&from_project_id={SOURCE_PROJECT_ID}&straight=true

Breadcrumb changes

The comparison is shown as if the changes from the source revision was being merged into the target revision.

Currently the breadcrumb is displayed as "Compare revisions > a...b", the proposal changes it to "Compare revisions > b to a".

The structure is {SOURCE_BRANCHNAME} to {TARGET_BRANCHNAME}.

image

Change the way "swap revision" works

Currently when the user clicks on "Swap revisions" the source and target revision swaps but nothing else happens until the user clicks on "Compare". If the page reloaded after pressing "Swap revisions" then this positioning would make sense.

To make this flow clearer, we are moving the swap button between the source and target revision and this way nothing is expected to happen after swapping revisions.

image

Design

Figma file

Only incoming changes from source Include changes to target since source was created
image image

States

Hover state Responsive
image image

Background information

There has been confusion on what ... means in the UI for the Compare page. This has been made even more evident with the addition of "straight" mode or .. (2-dot comparison) added with !80031 (merged).

With .. and ... as dropdown options it is hard to understand what they mean. Even well versed individuals with git can be confused as the meaning are opposite if you are looking at the command git diff or git log.

With the ambiguity of the dots, we should move away from using them as options and look for text that could communicate the comparison better. This sentiment is expressed in these other issues:

Our Compare page is using git diff as the commmand.

git command Meaning Diagram New UI Label
git diff A...B Shows commits of B since last common ancestor of A and B image Only incoming changes from source
git diff A..B Shows comparison of commits on both A and B since last common ancestor image Include changes to target since source was created

Venn diagrams from #20372 (comment 215091971)

CleanShot_2022-12-10_at_23.47.42

source: https://stackoverflow.com/a/46345364

Issues with the URL for the Compare page

When clicking on "Compare" from the side menu, the URL is:

  • /-/compare?from=B&to=A
    • Where this maps the UI as:
      • A => TARGET
      • B => SOURCE

This is fine until the user makes a comparison and the URL changes. The URL for the Compare has many elements because it is using a mix of git notation and querystrings.

  • /-/compare/A...B?from_project_id=12345&straight=true

By using the 3-dot notation in the URL, the order of the URL no longer matches the UI presentation of "Source" -> "Target".

-/compare/{TARGET_BRANCHNAME}...{SOURCE_BRANCHNAME}?from_project_id={SOURCE_PROJECT_ID}&straight={IS_STRAIGHT_COMPARSION}

Possible solutions for URL

  • We might want to consider swapping the Source and Target fields
    • to represent the same order as the URL. But then it would be weird to find Target before Source. #20372 (closed)
    • The GitLab display should match the git standard #382619 (closed)
    • Source/Target order matches how source/target branches are displayed in merge requests.
  • Rename those fields to From and To might be an option.

Availability and Testing

Update existing feature specs in line with UI changes.

Edited by Jay McCure