<!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION --> *This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.* <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION --> ## Problem to solve Reviewing merge request diffs is one of the most important capabilities of the merge request interface, given that is where the code being reviewed can be found and feedback given. The introduction of the file tree was an important iteration towards improving diff navigation, but it was merely the first step. As merge requests become larger navigation is still difficult. This has surfaced in feedback from customers and UX research. - **performance** is poor for anything but small merge requests because so much data is loaded - **scroll-based navigation** is not useful because the page is so long. Finding file boundaries using the mouse is very difficult - **keyboard-based navigation** is possible by using page down, but it isn't possible to move to the top and bottom of a file easily because it is essentially a keyboard powered scroll event - **collapsed/incomplete diff** to protect page performance means large files are automatically collapsed even thought these still need to be reviewed ## Further details The current approach is limited to: - viewing the first 1,000 changed files (alphabetically sorted) - collapsing files with over 100 changed lines This limitation has caused frustration for customers, both that some changes simply can't be reviewed in GitLab at all, and that important files are automatically collapsed making them hard to spot and review. A perfect illustration of this at GitLab is the monthly release post where the diff is always collapsed for the most important file in the merge request, and always buried below other data. ## Proposal A file-by-file diff mode would allow these limitations to be eased, if not removed entirely. - **default**, opening the changes tab will open the first file in the file tree/list - **deep linking**, open the corresponding diff, corresponding file, and scroll to the corresponding discussion This will require: - implementing new APIs, likely using ~GraphQL, to retrieve the diff for a specific file and corresponding discussions - interface changes to support both modes, since such a significant change should occur iteratively with extensive functional and user testing before considering changing the default code review behaviour - add new diff setting to allow users to test this new diff mode - implementing affordances for mouse based navigation: links to next/previous file below the diff (both links can be at the bottom of the file since code executes top to bottom) - ~~implementing affordances for keyboard based navigation: shortcuts to next/previous file~~ https://gitlab.com/gitlab-org/gitlab-ce/issues/48798 ## Benefits - :rocket: **Performance** - performance will be improved because **diffs** and **discussions** only need to be loaded for one file. Currently both diffs and discussions need to be loaded for every changed file - performance of deep linking a comment in a merge request should be massively improved because it will jump directly to that file, and only load the exactly needed data - performance is a usability improvement! - :mouse2: **Mouse-based navigation** - scroll resolution is improved be reducing the page height - the bottom of the diff can be reached using a flick gesture - the top of the diff will be more accessible, but will still be below the merge request description - :keyboard: **Keyboard-based navigation** - End key will behave as expected, taking the user to the bottom of the diff - Home key will be improved, taking the user to the top of the page, with top of the diff below the description - :thinking: **Concerns** - :mag: Searching the entire diff is possible using browser search. File-by-file diffs would break that. ~"needs investigation" - :ok_hand: For small changes to 5 files, moving all users to a file-by-file layout might be undesirable. We plan to conduct ~"UX research" using an opt-in MVC to determine impact on usability for these situations. We may be able to mitigate problems that are found sufficiently to make file-by-file merge request diffs the default behavior, or we may need to consider supporting both. ## Links / references