Merge branch 'docs-merge-ref-head-diffs' into 'master'

Add development docs on merge ref diffs

See merge request gitlab-org/gitlab!47211

doc/development/diffs.md

@@ -135,3 +135,51 @@ Diff Viewers, which can be found on `models/diff_viewer/*` are classes used to m
 whether it's a binary, which partial should be used to render it or which File extensions this class accounts for.
 
 `DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type in order to check if it can be rendered.
+
+## Merge request diffs against the `HEAD` of the target branch
+
+Historically, merge request diffs have been calculated by `git diff target...source` which compares the
+`HEAD` of the source branch with the merge base (or a common ancestor) of the target branch and the source's.
+This solution works well until the target branch starts containing some of the
+changes introduced by the source branch: Consider the following case, in which the source branch
+is `feature_a` and the target is `master`:
+
+1. Checkout a new branch `feature_a` from `master` and remove `file_a` and `file_b` in it.
+1. Add a commit that removes `file_a` to `master`.
+
+The merge request diff still contains the `file_a` removal while the actual diff compared to
+`master`'s `HEAD` has only the `file_b` removal. The diff with such redundant
+changes is harder to review.
+
+In order to display an up-to-date diff, in GitLab 12.9 we
+[introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27008) merge request
+diffs compared against `HEAD` of the target branch: the
+target branch is artificially merged into the source branch, then the resulting
+merge ref is compared to the source branch in order to calculate an accurate
+diff.
+
+Until we complete the epics ["use merge refs for diffs"](https://gitlab.com/groups/gitlab-org/-/epics/854)
+and ["merge conflicts in diffs"](https://gitlab.com/groups/gitlab-org/-/epics/4893),
+both options `master (base)` and `master (HEAD)` are available to be displayed in merge requests:
+
+![Merge ref head options](img/merge_ref_head_options_v13_6.png)
+
+The `master (HEAD)` option is meant to replace `master (base)` in the future.
+
+In order to support comments for both options, diff note positions are stored for
+both `master (base)` and `master (HEAD)` versions ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198457) in 12.10).
+The position for `master (base)` version is stored in `Note#position` and
+`Note#original_position` columns, for `master (HEAD)` version `DiffNotePosition`
+has been introduced.
+
+One of the key challenges to deal with when working on merge ref diffs are merge
+conflicts. If the target and source branch contains a merge conflict, the branches
+cannot be automatically merged. The [recording on
+YouTube](https://www.youtube.com/watch?v=GFXIFA4ZuZw&feature=youtu.be&ab_channel=GitLabUnfiltered)
+is a quick introduction to the problem and the motivation behind the [epic](https://gitlab.com/groups/gitlab-org/-/epics/854).
+
+In 13.5 a solution for both-modified merge
+conflict has been
+[introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232484). However,
+there are more classes of merge conflicts that are to be
+[addressed](https://gitlab.com/groups/gitlab-org/-/epics/4893) in the future.