Attempt to improve merge-conflicts modal
What does this MR do?
This MR removes merge conflicts resolving example from Checkout modal window in merge requests. These instructions are incorrect and shouldn't be followed. The link to the docs in the window already has proper instructions in place.
It also fixes minor typos regarding this modal window and removes any mentions of merging into target branch to resolve conflicts.
Additional details
This MR is really more frontend than documentation, so I'll do my best to kickstart it, then seek help to move it forward. I lack technical knowledge on two fronts: 1) doing the FE work to change the modal(s?) and 2) deep enough Git knowledge to be certain I'm recommending the right instructions to ALL users who see this merge-conflict modal window.
Notes for FE reviewer / helper:
-
I haven't been able to view my changes locally. GDK is stuck at Checking if merge request can be merged… and at some point I have to acknowledge I'm trying to do non-docs things here -
#383823 (closed) contains an excellent description of the current state. Please read it. -
Now compare the instructions in the modal to the instructions in the docs, because they're different: -
the modal describes checking out masterand usinggit merge --no-ffto merge the feature branch into it. Not all users have merge rights on the default branch (master/main), so these instructions won't work for everyone. -
the docs for 'resolve conflicts from the command line' instruct the user to instead rebase, then use git push --force-with-leaseto their feature branch. We could then encourage the user to return to the GitLab UI to complete the merge request.
-
-
My impression from @ipedowitz is that we should update the instructions in app/assets/javascripts/vue_merge_request_widget/components/mr_widget_how_to_merge_modal.vueto use the procedure we have in the docs, but updatingmr_widget_how_to_merge_modal.vueis out of scope for me as a technical writer, so I need to hand it off. -
Please, please double-check the instructions as part of the review process. This modal matters to a lot of users, and we need to get the instructions right. As a writer, I can help you polish the language and presentation, but I'm dependent on the engineers in my groups to make sure the info I'm polishing is actually correct.
Screenshots
| Before | After |
|---|---|
![]() |
![]() |
Related issues
- Related to Add link to docs about conflicts in the resolve... (#344883 - closed), and might even close it depending on what's done here
- Related to !73565 (comment 722054762)
- Related to Improve displayed instructions for local merge ... (#347154 - closed)
- Related to Merge conflict instructions don't work to fix l... (#383823 - closed)
Author's checklist
-
Optional. Consider taking the GitLab Technical Writing Fundamentals course. -
Follow the: -
If you're adding or changing the main heading of the page (H1), ensure that the product tier badge is added. -
If you are a GitLab team member, request a review based on: - The documentation page's metadata.
- The associated Technical Writer.
If you are a GitLab team member and only adding documentation, do not add any of the following labels:
~"frontend"~"backend"~"type::bug"~"database"
These labels cause the MR to be added to code verification QA issues.
Reviewer's checklist
Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.
If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.
-
If the content requires it, ensure the information is reviewed by a subject matter expert. - Technical writer review items:
-
Ensure docs metadata is present and up-to-date. -
Ensure the appropriate labels are added to this MR. -
Ensure a release milestone is set. - If relevant to this MR, ensure content topic type principles are in use, including:
-
The headings should be something you'd do a Google search for. Instead of Default behavior, say something likeDefault behavior when you close an issue. -
The headings (other than the page title) should be active. Instead of Configuring GDK, say something likeConfigure GDK. -
Any task steps should be written as a numbered list. - If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
-
-
-
Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

