Page MenuHomePhabricator

Simplify fork-and-merge-request workflow descriptions in local documentation
Closed, ResolvedPublicFeature

Description

https://www.mediawiki.org/wiki/GitLab/Workflows/Making_a_merge_request covers the technical details of using GitlLab to produce a merge request. That documentation however feels like it could be improved by separating the workflows of creating an MR against a repo where the change author has push privileges (is a project owner/maintainer) vs the more likely workflow of forking the repo to gain push rights. Leaving more technically complex topics like making a working copy dual homed to a read-only remote and a read-write remote for advanced tutorials or footnotes would also be reasonable.

We have folks in the technical community who are well versed in one or the other, but not both, of these MR workflow variations. Providing documentation that clearly shows when to use which workflow and the differences between them should make it easier to provide front line tech support.

Event Timeline

KBach changed the task status from Open to In Progress.Oct 4 2024, 10:19 AM
KBach claimed this task.
KBach added a subscriber: brennen.

I copied this page to my sandbox and made a few edits to see if I can improve it. @bd808 @brennen, can you have a look at https://www.mediawiki.org/wiki/User:KBach-WMF/Sandbox/GitLab_making_a_merge_request (diff) and let me know if this is moving in the right direction?

I think you are definitely making that content easier to follow @KBach. I especially appreciate the multi-remote workflow being pushed down to be a power user solution rather than a default instruction.

Thanks @bd808. I have now applied these changes to the original page (diff).

I'm considering one more change to the page to make it a little easier to scan. I've extracted key git commands into code snippets outside the example boxes. The change is visible in my sandbox copy of the page: https://www.mediawiki.org/wiki/User:KBach-WMF/Sandbox/GitLab_making_a_merge_request (diff). I'd appreciate your feedback.

I'm considering one more change to the page to make it a little easier to scan. I've extracted key git commands into code snippets outside the example boxes. The change is visible in my sandbox copy of the page: https://www.mediawiki.org/wiki/User:KBach-WMF/Sandbox/GitLab_making_a_merge_request (diff). I'd appreciate your feedback.

I like the idea. The interesting commands might show up even a bit more if instead of <code>git clone <repository address></code>
you used <syntaxhighlight lang=shell>git clone <repository address></syntaxhighlight>:

Screenshot 2024-11-08 at 09.49.41.png (270×2 px, 52 KB)

This is basically switching from an inline element to a block element.

Thanks @bd808, this is much better. The changes are now live. I'm resolving this task. Please feel free to reopen if you think it needs more work.