Make the labels in the Compare form less confusing21331-improve-confusing-compare-page

* Improve the descriptive text
* Rename "from" to "Target" and "to" to "Source"
* Swap "Target" and "Source" to have the same order as in MRs
* Reworded "Switch base of comparison" to "Swap versions"

Signed-off-by: Rémy Coutable <remy@rymai.me>

5 files changed, 28 insertions, 17 deletions

diff --git a/app/controllers/projects/compare_controller.rb b/app/controllers/projects/compare_controller.rb
index 193549663ac..3c8eaa24080 100644
--- a/app/controllers/projects/compare_controller.rb
+++ b/app/controllers/projects/compare_controller.rb
@@ -27,7 +27,7 @@ class Projects::CompareController < Projects::ApplicationController
 
   def create
     if params[:from].blank? || params[:to].blank?
-      flash[:alert] = "You must select from and to branches"
+      flash[:alert] = "You must select a Source and a Target revision"
       from_to_vars = {
         from: params[:from].presence,
         to: params[:to].presence
diff --git a/app/views/projects/compare/_form.html.haml b/app/views/projects/compare/_form.html.haml
index 94b7db5eb25..a518fced2b4 100644
--- a/app/views/projects/compare/_form.html.haml
+++ b/app/views/projects/compare/_form.html.haml
@@ -2,22 +2,22 @@
   .clearfix
     - if params[:to] && params[:from]
       .compare-switch-container
-        = link_to icon('exchange'), {from: params[:to], to: params[:from]}, {class: 'commits-compare-switch has-tooltip btn btn-white', title: 'Switch base of comparison'}
-    .form-group.dropdown.compare-form-group.from.js-compare-from-dropdown
-      .input-group.inline-input-group
-        %span.input-group-addon from
-        = hidden_field_tag :from, params[:from]
-        = button_tag type: 'button', title: params[:from], class: "form-control compare-dropdown-toggle js-compare-dropdown has-tooltip git-revision-dropdown-toggle", required: true, data: { refs_url: refs_project_path(@project), toggle: "dropdown", target: ".js-compare-from-dropdown", selected: params[:from], field_name: :from } do
-          .dropdown-toggle-text.str-truncated= params[:from] || 'Select branch/tag'
-      = render 'shared/ref_dropdown'
-    .compare-ellipsis.inline ...
+        = link_to icon('exchange'), { from: params[:to], to: params[:from] }, class: 'commits-compare-switch has-tooltip btn btn-white', title: 'Swap revisions'
     .form-group.dropdown.compare-form-group.to.js-compare-to-dropdown
       .input-group.inline-input-group
-        %span.input-group-addon to
+        %span.input-group-addon Source
         = hidden_field_tag :to, params[:to]
         = button_tag type: 'button', title: params[:to], class: "form-control compare-dropdown-toggle js-compare-dropdown has-tooltip git-revision-dropdown-toggle", required: true, data: { refs_url: refs_project_path(@project), toggle: "dropdown", target: ".js-compare-to-dropdown", selected: params[:to], field_name: :to } do
           .dropdown-toggle-text.str-truncated= params[:to] || 'Select branch/tag'
       = render 'shared/ref_dropdown'
+    .compare-ellipsis.inline ...
+    .form-group.dropdown.compare-form-group.from.js-compare-from-dropdown
+      .input-group.inline-input-group
+        %span.input-group-addon Target
+        = hidden_field_tag :from, params[:from]
+        = button_tag type: 'button', title: params[:from], class: "form-control compare-dropdown-toggle js-compare-dropdown has-tooltip git-revision-dropdown-toggle", required: true, data: { refs_url: refs_project_path(@project), toggle: "dropdown", target: ".js-compare-from-dropdown", selected: params[:from], field_name: :from } do
+          .dropdown-toggle-text.str-truncated= params[:from] || 'Select branch/tag'
+      = render 'shared/ref_dropdown'
     &nbsp;
     = button_tag "Compare", class: "btn btn-create commits-compare-btn"
     - if @merge_request.present?
diff --git a/app/views/projects/compare/index.html.haml b/app/views/projects/compare/index.html.haml
index 2632fea6eba..1ce3ad0c0fd 100644
--- a/app/views/projects/compare/index.html.haml
+++ b/app/views/projects/compare/index.html.haml
@@ -7,13 +7,19 @@
   .sub-header-block
     Compare Git revisions.
     %br
-    Fill input field with commit SHA like
-    %code.ref-name 4eedf23
-    or branch/tag name like
-    %code.ref-name master
-    and press compare button for the commits list and a code diff.
+    Choose a branch/tag (e.g.
+    = succeed ')' do
+      %code.ref-name master
+    or enter a commit SHA (e.g.
+    = succeed ')' do
+      %code.ref-name 4eedf23
+    to see what's changed or to create a merge request.
     %br
-    Changes are shown <b>from</b> the version in the first field <b>to</b> the version in the second field.
+    Changes are shown as if the
+    %b source
+    revision was being merged into the
+    %b target
+    revision.
 
   .prepend-top-20
     = render "form"
diff --git a/changelogs/unreleased/21331-improve-confusing-compare-page.yml b/changelogs/unreleased/21331-improve-confusing-compare-page.yml
new file mode 100644
index 00000000000..469cc04930b
--- /dev/null
+++ b/changelogs/unreleased/21331-improve-confusing-compare-page.yml
@@ -0,0 +1,5 @@
+---
+title: Make the labels in the Compare form less confusing
+merge_request: 14225
+author:
+type: changed
diff --git a/doc/user/project/repository/img/compare_branches.png b/doc/user/project/repository/img/compare_branches.png
index 353bd72ef4e..d7ab587f030 100755..100644
--- a/doc/user/project/repository/img/compare_branches.png
+++ b/doc/user/project/repository/img/compare_branches.png