Revamp Merge Request documentation
What does this MR do?
Merge Request documentation needs a full revamp. It's a fundamental part of working with GitLab, but the barrier to entry is quite high. As identified in &1678 (closed), this is a weakness in our documentation.
Changes
- Make the index page a better landing page for those who are new to GitLab and merge requests, separating out the feature documentation to different pages:
- Features already listed on their own page will remain unchanged.
- Links out to documentation for MR-related features grouped in tables based on:
- Creating MRs
- Reviewing/Managing MRs
- Reports displayed in MRs (ex: testing)
- Features described in the index moved to:
- new
creating_merge_requests.md
- new
reviewing_and_managing_merge_requests.md
- new
- Remove all tiny sections that do nothing but link to another page.
Phase 2 (another MR): Add an expanded intro to the Reviewing/Managing MRs doc.
Phase 3 (another MR) to evaluate the old content itself, and check the if more information can be combined, or if other changes should be made. The top image should be re-evaluated as well.
Current Status
- The MR doc index was cut from 600+ lines to <120 lines. "Doubly linked" things (links from the top that go to the middle of the index, only to link again to another page) are removed.
- Anything related to creating MRs is on a new page with a new intro and basic MR details that didn't seem to exist anywhere at all. Nesting of these sections improved as well.
- Anything related to reviewing/managing MRs is on another new page. Less work on this since it's not the OKR focus. Will expand intro and add more details in a follow-up MR. No information was lost.
- The massive list near the top of the index completely removed, and added into the three tables of easy-to-read details, which will be easier to maintain as new features are added.
- The feature content is unchanged.
- The new content is mostly introductory sections for:
-
creating_merge_requests.md
(from top to## assignee
) -
reviewing_and_managing_merge_requests.md
(short intro at top) - Simple intro for
index.md
and for the 3 new sections.
-
Review notes:
All the content relating to features themselves (that were moved into the two new pages) was untouched except to fix links.
The reviewer should focus on:
- whether or not the new locations for the features make sense
- review the new text:
- Table content (descriptions taken from list in previous MR doc)
- Intros to the new pages, and the new sections in the index.
Related issues
Related to #31708 (closed)
Changes as seen in TOC
(minor changes since this image was added, but generally the same)
Author's checklist
-
Follow the Documentation Guidelines and Style Guide. -
If applicable, update the permissions table. -
Link docs to and from the higher-level index page, plus other related docs where helpful. -
Apply the documentation label.
Review checklist
All reviewers can help ensure accuracy, clarity, completeness, and adherence to the Documentation Guidelines and Style Guide.
1. Primary Reviewer
-
Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes.
2. Technical Writer
-
Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable DevOps stage.
3. Maintainer
-
Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review. -
Ensure a release milestone is set and that you merge the equivalent EE MR before the CE MR if both exist. -
If there has not been a technical writer review, create an issue for one using the Doc Review template.