Description Stefan Xenos 2017-05-11 00:50:51 EDT

The goal of the proposed rules is to make Compare viewer display consistent with popular code review systems, e.g. Gerrit, and with popular file comparison programs like meld or tkdiff. To the degree possible the rules also try to guarantee consistency between different comparison operations when the same change is viewed at different times in its life.

This draft proposal came from a number of discussion notes and emails between sprigogin and sxenos.

We believe that the reason other tools are unambiguous is because they always fall into one of two cases:
1. The user is viewing an existing change where someone already selected the before and after states.
2. The user explicitly selected which state goes on which side of the viewer.

Examples of 1:
- Viewing a .diff file
- Viewing a commit in gerrit
- Viewing an existing change in gitk
- Viewing your change in progress in "git gui"

Examples of 2:
- Any command-line tool where the order of command-line arguments controls the side where things appear (tkdiff, kdiff, p4merge)
- The dropdowns in gerrit that let you manually control what patch version shows up on each side of the diff viewer

In other words, the choice of before/after, left/right is always something that was explicitly chosen by someone. *This* is the rule that unifies most non-Eclipse tools, and that it's what we're promising to do when we say we're making Eclipse consistent with other tools. For example, it is our belief that most users wouldn't want their command-line tool to choose which file state goes on the left and right based on something like timestamp.

We only need three rules to apply this consistently in Eclipse.

Actions where the before/after states are unambiguous and were already selected (possibly by someone else) get a different verb ("Show") from ones where the user will select the left-right sides themselves ("Compare").
1. Context menu items named "Compare" or "Compare with" put the thing you right-clicked on on the left, and any other state on the right.
2. Double-click actions, preview windows, and actions named "Show" should only be used in places where a before and after state is unambiguous and meaningful. They put the before state on the left, and after state on the right.
3. In the case of a preview, the "before" state is the current state of the workspace and the "after" state is the hypothetical future state.

Concretely:

A) Refactoring preview. Proposed change is shown on the right (rule #2).
B) Replace With Local History. The history version is shown on the right (rule #2).
C) Compare Current with Local in the local history view. The workspace version is shown on the right (rule #2).
D) Compare with Each Other in local history view. See note N2, below.
E) Compare With Previous Version (EGit) (on IResource). Action renamed to "Show changes since previous commit". The workspace version is shown on the right (rule #2).
F) Compare With HEAD Revision (EGit) (on IResource). Action renamed to "Show uncommitted changes". The workspace version is shown on the right (rule #2).
G) Compare With Index (EGit). Action renamed to "Show unstaged changes". The workspace version is shown on the right (rule #2).
H) Compare With Branch, Tag, or Reference (EGit). The workspace version is shown on the left (rule #1).
I) Compare With Commit (EGit). The workspace version is shown on the left (rule #1).
J) Replace With Branch, Tag, or Reference (EGit). The selected version to be used as a replacement is shown on the right (rule #3).
K) Replace With Commit (EGit). The selected commit version to be used as a replacement is shown on the right (rule #3).
L) Compare With Index With HEAD (EGit). Action renamed to "Show staged changes". The index version is shown on the right (rule #2).
M) Compare with Previous Version in History view (EGit). Action renamed to "Show change". The later version is on the right (rule #2).
N) Compare with Working Tree in History view (EGit). The working tree version is shown on the right (rule #1).
O) Compare with Each Other in History view (EGit). See note N2, below.
P) Compare With Each Other in Navigator. See note N2, below.
Q) "Open" in History view (EGit). The later version is on the right (rule #2).
R) Compare with Workspace in History view (EGit). It will continue to keep its current name. The workspace version is shown on the right (rule #1).


Notes:
N1) For any action named "compare", there should always be two ways to invoke the action, allowing the user to view whatever state they want on the left or right. In both situations, the thing the user right-clicked on will always be on the left and the "other" state (which is sometimes implicit) goes on the right. So, for example, the "Compare with Branch, Tag, or Reference" action on IResource and the "Compare with Working Tree" action in the history view can be used to view the same two file states from opposite directions. This is analogous to command-line diff tools where the user may pass whatever state they want as the first and second arguments.

N2) In the case of the two-selection "Compare with Each Other" actions (D, O, P), we have three options. 
N2A) We can either rename these actions to "Show differences" to avoid the verb of "compare", which now has more rigorous semantics.
N2B) The actions are replaced by a new action called "Compare with Version..."/"Compare with File...", etc. which opens a dialog for selecting the right-hand state.
N2C) All such actions can be removed and replaced with a new action called "Compare with Clipboard", combined with additional "Copy" actions that allow you to copy any file state that currently can be the target of one of these "Each other" actions. "Compare with Clipboard" would show the right-clicked version on the left and the clipboard version on the right.

We'd suggest N2C. This would 
- Resolve the ambiguity over which side of the compare viewer is which.
- Give the user control over which way they view their diff.
- Permit a bunch of useful comparisons that aren't currently possible (such as comparing a historical version of one file with the workspace version of another).
- Provide better keyboard accessibility, since nonconsecutive keyboard selections are difficult to do in large views.

N3) Issues with the "Show" actions:

This proposal suggests renaming a bunch of "Compare with XXX" actions to "Show YYY". Many of these actions currently appear below the "Compare With" dropdown on IResource and they have action names of the form XXX such that the sentence "Compare with XXX" parses as a valid English sentence. This could be seen as a flaw in this proposal. It can be resolved in three ways:

N3A) We can ignore it
- There is already precedent for actions in the Compare With submenu that don't form a valid English sentence when prefixed by "Compare With XXX" - namely, the "Index With HEAD" action.
- The fact that these actions work as sentences is a coincidence of English and languages with an English-like word order. Switching to action names that are meaningful in themselves would provide translation strings that are equally meaningful in all languages, even if the English versions would get more verbose.

N3B) The actions can move to the Team menu
- These same actions already appear outside the Compare With submenu when invoked from other contexts (such as the history view), so moving them to another menu is reasonable - particularly if they get new names starting with "Show". There are already other actions in the Team menu named Show that open new UI, and these would be consistent with that metaphor.

N3C) We rename the "Compare With" menu to "Compare"
- This removes the expectation that the elements in the dropdown are nouns that complete an English sentence and brings this menu in line with the rest of the Eclipse UI, where action names are expected to be verbs.

Summary:

The ambiguity of our current compare actions arises because we make use of properties of the selection to determine what side each file state appears on. We can't fix this by selecting a better set of properties. The sort of comparison that the user wants to perform depends entirely on what they are doing at the time, not the file states they've selected - so the determination of what goes on which side of the editor should be entirely under the user's control using only the user's gestures and no additional smarts.