forked from docs/team-docs
WebIDE guide updated with a new template
This commit is contained in:
parent
dad3a402a4
commit
940a71a368
1 changed files with 35 additions and 27 deletions
|
|
@ -1,22 +1,25 @@
|
|||
= HowTo for casual contributions
|
||||
= How to make casual contributions
|
||||
Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
|
||||
2023-01-23
|
||||
:revdate: 2023-03-15
|
||||
|
||||
== Create and propose a change in a Docs page
|
||||
[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.
|
||||
|
||||
-> *There is no preceding knowledge of git or merge requests necessary!*
|
||||
- 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 ... and all editing will be done in a GUI within your browser.
|
||||
|
||||
-> *This HowTo is for GitLab-based pages only. If you were forwarded here by a link on any docs.fedoraproject.org page, you are in the right place!*
|
||||
- This guide is for GitLab-hosted repo; https://gitlab.com/fedora/docs
|
||||
|
||||
== Select a page to edit
|
||||
== How to use Web IDE
|
||||
|
||||
If you have found something on a Docs page which you want to add, remove, change, or update, you will see three buttons on the top right
|
||||
which can be used to directly put forward your suggestion without knowledge of git or the structures with which the Docs pages are
|
||||
organized (repository structures). The buttons will forward you correspondingly.
|
||||
=== Select a page to edit
|
||||
|
||||
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 suggestions:
|
||||
If you found something on a Docs page you want to edit, navigate to the top right and locate to 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:
|
||||
|
||||
|===
|
||||
a|image::1CUT-changeIdentified.png[align="center",role=black-border]
|
||||
|
|
@ -28,17 +31,17 @@ 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]
|
||||
|
||||
NOTE: If you have already a GitLab account and if you want to link it to your FAS account, you have to log into your existing GitLab account **before** you use the above FAS link!
|
||||
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.
|
||||
|
||||
|===
|
||||
a|image::2-GitLabSignin.png[align="center",width=940,role=black-border]
|
||||
|===
|
||||
|
||||
NOTE: Since GitLab 15.7, a new default Web IDE editor has been introduced, whereas the old one will be removed from GitLab mid 2023. Thus, this guide focuses already on the new <<web-ide-editor,Web IDE editor>> to submit your contribution. Alternatively, you can choose to use the simple https://docs.gitlab.com/ee/user/project/repository/web_editor.html#edit-a-file[Web Editor]. When using the Web Editor, you can follow the steps on the related https://docs.gitlab.com/ee/user/project/repository/web_editor.html#edit-a-file[GitLab guide] instead of the <<web-ide-editor,Web IDE editor>> section here, and then proceed directly to the <<merge-request,Merge request>> section below.
|
||||
NOTE: Since GitLab 15.7, a new default Web IDE editor has been introduced. This guide focuses on the new <<web-ide-editor,Web IDE editor>>. Alternatively, you can use the simple https://docs.gitlab.com/ee/user/project/repository/web_editor.html#edit-a-file[Web Editor]. When using the Web Editor, follow the steps on the related https://docs.gitlab.com/ee/user/project/repository/web_editor.html#edit-a-file[GitLab guide] instead of the <<web-ide-editor,Web IDE editor>> section here, and then proceed directly to the <<merge-request,Merge request>> section below.
|
||||
|
||||
[[web-ide-editor]]
|
||||
== Web IDE editor
|
||||
Click the "Open in Web IDE" button:
|
||||
=== Launch Web IDE and fork the project
|
||||
|
||||
Click the "Open in Web IDE" button. Alternatively, press . (dot) to launch Web IDE.
|
||||
|
||||
|===
|
||||
a|image::3-EditPage.png[align="center",width=940,role=black-border]
|
||||
|
|
@ -46,23 +49,29 @@ a|image::3-EditPage.png[align="center",width=940,role=black-border]
|
|||
|
||||
Click the "Fork" button:
|
||||
|
||||
NOTE: The "Fork" button appears only the first time you contribute to the repository of a given Docs page. If you have already "forked" that repository before (e.g., during an earlier contribution), you will be forwarded automatically to the next step without 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.
|
||||
|
||||
If you have already "forked" that repository before (e.g., during an earlier contribution), you will be forwarded automatically to the next step without the "Fork" button.
|
||||
|
||||
|===
|
||||
a|image::4-EditFork.png[align="center",width=940,role=black-border]
|
||||
|===
|
||||
|
||||
NOTE: 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, 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.
|
||||
|
||||
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.
|
||||
Then make the necessary changes to the page. Please refer to the style guide for consistency: https://gitlab.com/-/ide/project/Klaunch/documentation-contributors-guide/merge_requests/49?target_project=fedora%2Fdocs%2Fcommunity-tools%2Fdocumentation-contributors-guide
|
||||
|
||||
|===
|
||||
a|image::webuibeta-1.png[align="center",width=940,role=black-border]
|
||||
|===
|
||||
|
||||
\... once you've finished, click on both the branch (source contrrol) icon and the file (underneath 'Commit & Push' button) to view your changes. Type a commit message and click "Commit & Push":
|
||||
=== Commit and push your changes to a branch
|
||||
|
||||
Once you've finished, click on both the branch (source contrrol) icon and the file (underneath 'Commit & Push' button) to view your changes. Type a commit message and click "Commit & Push":
|
||||
|
||||
|===
|
||||
a|image::webuibeta-2a.png[align="center",width=940,role=black-border]
|
||||
|
|
@ -86,34 +95,33 @@ Click on "GitLab" in the bottom left-hand corner. This will bring up a dialog wi
|
|||
a|image::webuibeta-6a.png[align="center",width=940,role=black-border]
|
||||
|===
|
||||
|
||||
=== Merge request
|
||||
|
||||
Click "Create merge request" on the banner that appears (you will be directed to a <<merge-request,merge request>>):
|
||||
|
||||
|===
|
||||
a|image::webuibeta-8.png[align="center",width=940,role=black-border]
|
||||
|===
|
||||
|
||||
[[merge-request]]
|
||||
== Create a merge request
|
||||
|
||||
Edit the Title and the Description of the page (feel free to copy-paste the Commit Message) and then, scroll down to the blue "Create merge request" button and click it:
|
||||
Edit the title and the description of the page and then, 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 newly-created merge request:
|
||||
This will bring up the new merge request:
|
||||
|
||||
|===
|
||||
a|image::C-MR.png[align="center",width=940,role=black-border]
|
||||
|===
|
||||
|
||||
The process is complete! You can ignore any issues about "branches". But feel free to add comments and discuss your suggestions with the Fedora Docs team. You can always return to this page later.
|
||||
Your request to merge changes will be reviewed by Docs team. The process is complete!
|
||||
|
||||
|===
|
||||
a|image::D-CommentsInMR.png[align="center",width=940,role=black-border]
|
||||
|===
|
||||
|
||||
Also, feel free to comment if any Fedora releases are affected. However, this is not obligatory:
|
||||
We appreciate your feedback via GitLab issue board if any documentation bugs are found.
|
||||
|
||||
|===
|
||||
a|image::E-MRwithComments.png[align="center",width=940,role=black-border]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue