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

Contributor guide update for GitLab documentation

Browse source
This commit is contained in:
hank L 2023-05-21 20:37:55 +00:00 • committed by Peter Boy
commit bb6ae28c4d
3 changed files with 29 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
modules/ROOT/assets/images/gitlab-ui/create-mr.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 86 KiB

BIN
modules/ROOT/assets/images/gitlab-ui/editor.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 90 KiB

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

@ -1,6 +1,6 @@
= How to make casual contributions
Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
:revdate: 2023-05-14
:revdate: 2023-05-16
:page-pagination:
[abstract]
@ -12,13 +12,16 @@ To make changes in Docs page hosted on GitLab, you have a built-in web editor th
- This guide is for GitLab-hosted repo.
== How to use Web IDE
== How to edit document with Web IDE
=== Step 1. Select a page to edit
If you found something on a Docs page you want to edit, navigate to the top right and locate 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 latest Fedora release.
On left of the buttons, you see the latest Fedora release. The left button forwards to the version history of the opened Docs page as a reference. 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.
- The left button forwards to the version history of the opened Docs page as a reference.
- The middle *edit the page* button 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]
@ -28,9 +31,12 @@ a|image::1CUT-changeIdentified.png[align="center",role=black-border]
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]
- Log in to your existing GitLab account
- Use the https://gitlab.com/groups/fedora/-/saml/sso[SAML link] to link your account to FAS
- You will be redirected and asked for your FAS credentials if needed
- Grant permission to Fedora
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.
Create one if you do not have one yet (see the image below).
|===
a|image::2-GitLabSignin.png[align="center",width=940,role=black-border]
@ -38,7 +44,7 @@ a|image::2-GitLabSignin.png[align="center",width=940,role=black-border]
NOTE: This contributor guide walks through the new Web IDE, introduced in GitLab 15.7 release. The guide also reflects a latest change about *how to update fork*.
=== Step 2. Launch Web IDE and fork the project
=== Step 2. Create your project (copy)
Click the *Open in Web IDE* button. Alternatively, press . (dot) in keyboard to launch Web IDE.
@ -81,7 +87,7 @@ image::gitlab-ui/update-fork-yes.png[]
- The fork will display *Up to date with the upstream repository*
- *Update fork* button disappears after fork is updated
=== Step 3. Create a new branch
=== Step 3. Create a new branch (version)
On your forked project, create a new branch and switch to it following the steps below.
@ -95,59 +101,50 @@ On your forked project, create a new branch and switch to it following the steps
Are you sure you want to checkout <branch-name>? Any unsaved changes will be lost.
----
=== Step 4. Write, preview, edit and repeat
=== Step 4. Edit and save changes
Now, make the necessary changes in Web IDE. To write with consistency, refer to xref:contributing-docs/style-guide.adoc#prerequisites[The docs style guide]
|===
a|image::webuibeta-1.png[align="center",width=940,role=black-border]
|===
=== Step 5. Commit and push your changes to a branch
.Editor UI
image::gitlab-ui/editor.png[]
Once you've finished, select the source control button and click the file underneath *changes* below *Commit & Push* button) to view your changes.
Type a commit message and click *Commit & Push*. Click No to commit to existing branch.
=== Step 6. Merge request
=== Step 5. Create Merge Request (MR)
In the lower-right corner, you will find three options - *create MR*, *Go to project*, *Continue working*.
.Create MR button
image::gitlab-ui/commit.png[]
Click *Create MR* to create merge request. *Go to project* option is suitable when you made small commits by stage and want to squash them into one.
- Click *Create MR* to create merge request. *Go to project* option is suitable when you made small commits by stage and want to squash them into one.
- *Continue working* is when you want to make smaller commits by sub tasks. If you select *Create MR*, the UI will navigate to merge request.
- Edit the title and the description of the page.
- Scroll down to the blue *Create merge request* button and click it. This will bring up the new merge request.
*Continue working* is when you want to make smaller commits by sub tasks. If you select *Create MR*, the UI will navigate to merge request.
.Merge Request
image::gitlab-ui/create-mr.png[]
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]
|===
This will bring up the new merge request. If merge request is successful, you will see the following result in the lower-middle of merge request.
If merge request is successful, you will see the following result in the lower-middle of merge request.
----
Ready to merge by members who can write to the target branch.
----
Your branch (source branch) will be deleted when merge request is accepted. A checkbox for this option is selected by default to avoid stale branch and resultant merge conflict.
=== Step 6. Review
=== Step 7. Post MR review
Your request to merge changes (MR) will be reviewed by Docs team. You will expect one of the following actions.
Your request will be reviewed by Docs team. You will expect one of the following actions.
- Reviewers ask you to revise your changes
- Approve
- Reject to close MR within reason
- Reject and close MR within reason
Whatever the case it is, MR comments facilitate collaboration between contributors and reviewers. Everyone can learn from those comments and corrections.
Once your MR is approved, the process is complete.
We appreciate your feedback via GitLab issue board if any documentation bugs are found.
Thanks for your contribution!