How to make casual contributions
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. You do not need special permissions or write access to the original project.
-
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.
-
This guide is for GitLab-hosted repo; https://gitlab.com/fedora/docs
How to use Web IDE
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.
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 change or update.
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.
|
|
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
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.
|
| From GitLab 15.7, a new Web IDE was introduced. This guide focuses on the new Web IDE. |
Launch Web IDE and fork the project
Click the Open in Web IDE button. Alternatively, press . (dot) in keyboard to launch Web IDE.
|
Fork a project first time
Click the Fork button.
The Fork button appears only the first time you contribute to the repository of a given Docs page. If you are contributing to the Fedora project first time and you do not have write access for the repository you want to contribute to, you need to fork a project.
A fork is a personal copy of the repository, which you create in your namespace.
|
Forked a project before
If you have a forked repository (e.g., during an earlier contribution), you will be forwarded automatically to the next step without the Fork button.
If you do not launch Web IDE from your fork, edit fork in Web IDE button will appear in lieu of the Open in Web IDE button. Then you will be prompted to go to fork and checkout to your fork.
| 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 15.11 release is expected to fix the issue by April 17 2023. |
Write, preview, edit and repeat
Now, make the necessary changes in Web IDE. To write with consistency, refer to The docs style guide
|
Commit and push your changes to a branch
Once you’ve finished, click on both the branch (source control) icon and the file (underneath Commit & Push button) to view your changes. Type a commit message and click Commit & Push.
|
Click on Yes Commit to a new branch.
|
Enter a branch name and press enter.
|
Click on GitLab in the bottom left-hand corner. This will bring up a dialog with the Go to GitLab option. Click on it.
|
Merge request
Click Create merge request on the banner and you will be directed to a merge request)
|
Edit the title and the description of the page. Next, scroll down to the blue Create merge request button and click it.
|
This will bring up the new merge request.
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.
|
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 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 merge request is approved, the process is complete!
|
We appreciate your feedback via GitLab issue board if any documentation bugs are found.
|
Thanks for your contribution!
Want to help? Learn how to contribute to Fedora Docs ›