egret/team-docs
1
0
Fork 1
forked from docs/team-docs
Code Pull requests Wiki Activity

Merge request process made more descriptive. Abstract tidied up

Browse source
This commit is contained in:
Test Lab 2023-03-16 14:36:02 +00:00
commit 8285ce173f
1 changed files with 20 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

30
modules/ROOT/pages/contributing-docs/tools-gitlab-howto.adoc
View file

@ -1,13 +1,13 @@
= How to make casual contributions
Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
:revdate: 2023-03-15
:revdate: 2023-03-16
[abstract]
To make changes in a Docs page hosted on GitLab, you have a built-in editor that makes your first contribution easier than ever.
To make changes in Docs page hosted on GitLab, you have a built-in web editor that makes your first contribution easier than ever. Start editing documentation on GitLab Web IDE that you can launch in one click.
- There is no need to install apps or clone repos on your local computer, or run git commands in terminal.
- There is no risk of breaking anything ... and all editing will be done in a GUI within your browser.
- There is no risk of breaking anything.
- This guide is for GitLab-hosted repo; https://gitlab.com/fedora/docs
@ -15,11 +15,11 @@ To make changes in a Docs page hosted on GitLab, you have a built-in editor that
=== Select a page to edit
If you found something on a Docs page you want to edit, navigate to the top right and locate to three buttons.
If you found something on a Docs page you want to edit, navigate to the top right and locate three buttons.
On left of the buttons, you see the Fedora release (e.g., "F36") to which the Docs page you have opened relates to. Docs pages relate to a specific Fedora release, although changes/updates can apply to several releases' Docs pages. If the latter is the case just choose any version that needs the change/update. If you do not know what version the update applies to, then ignore it for the time being.
The left button forwards to the version history of the opened Docs page and is *not* relevant for you. The middle button "edit the page" opens up a source file for change/update. The right button "report an issue" is when you report any change/update required. Click the middle ("edit the page") button to make corrections:
The left button forwards to the version history of the opened Docs page and is not relevant for you. The middle button "edit the page" opens up a source file for change or update. The right button "report an issue" is when you report any change or update required. Click the middle ("edit the page") button to make corrections:
|===
a|image::1CUT-changeIdentified.png[align="center",role=black-border]
@ -31,7 +31,7 @@ a|image::1A-changeIdentified.png[align="center",width=940,role=black-border]
Now log in to your GitLab account or create one if you do not have one yet (see the image below). Alternatively, you can also use the Fedora Account System (FAS) to log into GitLab, but you have to do this in advance before clicking the "edit the page" button with the following link: https://gitlab.com/groups/fedora/-/saml/sso[https://gitlab.com/groups/fedora/-/saml/sso]
If you have already a GitLab account and if you want to link it to your FAS account, log into your existing GitLab account before you use the above FAS link.
If you have already a GitLab account and want to link it to your Fedora account, log into your existing GitLab account before you use the above FAS link.
|===
a|image::2-GitLabSignin.png[align="center",width=940,role=black-border]
@ -59,11 +59,11 @@ If you have already "forked" that repository before (e.g., during an earlier con
a|image::4-EditFork.png[align="center",width=940,role=black-border]
|===
If you have forked the repository before but your fork is already outdated, it can happen that you have not all current branches. If this is the case, GitLab will show you a blue "Create branch" button on the top left of the subsequent page after you clicked "Open in the Web IDE": if that happens, just click the "Create branch" button so that GitLab can do the rest for you. Then, proceed here as usual.
If you have forked the repository before but your fork is already outdated, you do not have all current branches. If this is the case, GitLab will show you a blue "Create branch" button on the top left of the subsequent page after you clicked "Open in the Web IDE": if that happens, just click the "Create branch" button so that GitLab can do the rest for you. Then, proceed here as usual.
CAUTION: If you have forked the repository before, and if you have already the related branch, GitLab will not check if your fork's branch is up to date: it will forward you to the respective file in the related branch of your fork even if this file is no longer up to date. GitLab knows about the https://gitlab.com/gitlab-org/gitlab/-/issues/330243[problem] and it is planned to solve this problem with the release of the https://gitlab.com/groups/gitlab-org/-/milestones/85#tab-issues[15.10 release] by the end of *March 2023*. Until then, you have to keep careful if you see neither a "Fork" button nor a "Create branch" button: in this case, check if your file is up to date before start working! If it is not, wait for the 15.10 release, or if you know how to: update your fork, or remove it & re-fork the repository. Alternatively, get in touch with the Docs team https://chat.fedoraproject.org/#/room/#docs:fedoraproject.org[here] or https://discussion.fedoraproject.org/[here]!
Then make the necessary changes to the page. Please refer to the style guide for consistency: https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/
Then make the necessary changes in Web IDE. Please refer to the style guide to write with consistency: https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/style-guide/
|===
a|image::webuibeta-1.png[align="center",width=940,role=black-border]
@ -103,7 +103,7 @@ Click "Create merge request" on the banner that appears (you will be directed to
a|image::webuibeta-8.png[align="center",width=940,role=black-border]
|===
Edit the title and the description of the page and then, scroll down to the blue "Create merge request" button and click it:
Edit the title and the description of the page. Next, scroll down to the blue "Create merge request" button and click it:
|===
a|image::B-EditTitleAndCreateMR.png[align="center",width=940,role=black-border]
@ -115,7 +115,17 @@ This will bring up the new merge request:
a|image::C-MR.png[align="center",width=940,role=black-border]
|===
Your request to merge changes will be reviewed by Docs team. The process is complete!
Your request to merge changes will be reviewed by Docs team. You will expect one of the following actions.
- Reviewers ask you to revise your changes.
- Approve
- Reject
Whatever the case it is, MR comments facilitate collaboration. Everyone can learn from those comments and corrections.
Once your merge request is approved, the process is complete!
|===
a|image::D-CommentsInMR.png[align="center",width=940,role=black-border]