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:
- UI change
- Remove dropdown for comparison mode changes
- Breadcrumb changes
- 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 |
---|---|
UI changes
- Page title changes from "Compare Git revisions" to
Compare revisions
- Add link to docs help "Learn more about comparing revisions"
- Label "Commits (#)" changes to
Commits on Source (#)
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
- URL structure:
- Legend label:
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}
.
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.
Design
Only incoming changes from source | Include changes to target since source was created |
---|---|
States
Hover state | Responsive |
---|---|
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.
Venn diagrams from #20372 (comment 215091971)
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
- Where this maps the UI as:
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
andTarget
fields- to represent the same order as the URL. But then it would be weird to find
Target
beforeSource
. #20372 - The GitLab display should match the git standard #382619 (closed)
- Source/Target order matches how source/target branches are displayed in merge requests.
- to represent the same order as the URL. But then it would be weird to find
- Rename those fields to
From
andTo
might be an option.- MR that changed From/To to Source/Target gitlab-foss!14225 (merged)
Availability and Testing
Update existing feature specs in line with UI changes.