Need help trying to suggest edits to Fedora Docs

I updated these steps if anyone’s got time to review it:

Merge request

2 Likes

@anthonymcglone thanks for taking care of that!

We have a draft for an updated “casual contribution” guide: Updated 7-steps GitLab guide for casual contributions (#15) (!23) · Merge requests · fedora / Fedora Docs / Community and Tools Documentation / Documentation Contributors Guide · GitLab

If you don’t want to clone+build the preview, I have created a tar file that contains the preview page so that you can just open it in a browser: file (the whole tar file needs to be extracted: the html file needs the content of the folder that is also in the tar)

Of course everyone shall feel free to review the new guide and let us know their thoughts! The more feedback we get, the more we can adjust the guide to your needs :slight_smile:

1 Like

Sorry, I didn’t mean to rush ahead, but just merged it before I read your comment. It is definitely an improvement, and I wanted to enable comments from our users as soon as possible.

1 Like

No worries :wink: You are right, it is definitely an improvement; it makes sense to merge immediately to make the guide usable again :wink: Indeed, now that you pointed it out, the merge might even make it easier for users to provide feedback. Let’s see what feedback is to come.

The guide will be available in around 1 hour at: https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/tools-7step-gitlab-howto/ - forget the file above :wink:

The file name on the link appeared to be changed;

New UI guide

Indeed, thanks for the corrected link! I just saw that accidentally the header name in the source file now contains “Fedora Docs”, which is usually automatically added during page generation. So now this is mentioned twice in the generated page’s header. Nothing critical, I will take care of that in the next days.

Done with commit 550cabfe :smile:

@anthonymcglone @pboy I don’t understand the new versioning of the pages: how is the version determined? I saw that the Casual Contribution HowTo is now determined 0.0.2, whereas, e.g., the How to Create and Use a Local Fedora Documentation Workflow is considered 1.0?

I think that version numbers are arbitrary or maybe a left over from the former wiki pages. We should leave these off and use the
:revnumber: F35-F37
:revdate: 2022-11-25
notification.

In case of our team pages, maybe we should just use :revdate:

As the guides are different for GitLab/Pagure/web IDE pages, it will help on how to verify which one is needed, and a link to the correct guide will help.

I would like to know how to see the status of my “contributions” as well. And sometimes, there might be discussion happening about the “merge request”, which will be nice for the “contributor” to know about.

Thank you for sharing.

I am trying to follow the guide, after clicking “Edit”, I got this link:

When clicking on “Open in Web IDE”, I got:

Should I just click “Create branch”?

I’m not active user of WebIDE, but only walked through a few times to get hands on with it.
Writers and editors of this article will guide you first hand experience with WebIDE.

1 Like

@sampsonf The problem is that you have worked in this repo before, but your own fork has not been updated for too long (the fork in your repo contains only branches up to F36, but it did not yet “pull” the F37 fork).

Therefore, in this case, you can do “create branch” and test, as GitLab suggests. I hope the “create branch” feature works out well for our purposes. It would be nice if you keep us informed!

Thanks by the way for your incentives. We have to think about how to handle such issues because you will likely be not the only one to experience that. This will happen again when we create and migrate to the F38 branch. Maybe I add a TIP or a NOTE box to GitLab that details this situation.

We also need to consider that a comparable issue can take place if the branch already exists in a user’s fork but if it is not yet updated with all commits from the Docs’ repo. I will try to find some time to test this in the coming days (everyone feel free to pick this up) but my hope is that GitLab will offer a comparable feature to just click to update the fork so that users can then make their preferred edit. Let’s see.

1 Like

Concerning the status of your contribution: after working through the HowTo, you end up on the page of the merge request. This is where the discussion takes place. The page link will not change so you can just save it as bookmark or so (see the steps/snapshots from the merge request section).

Concerning which guide to use: on one hand, when you click the “edit” button on the respective page, you can see if you end up on a pagure or gitlab page. However, you do not need to find out yourself: if you are on a page you want to edit, you should see left of the search box at the top a button with the name “7-steps guide” or something like that. This button will lead you to the correct HowTo. If there is no button, this usually means that we have currently no HowTo for this git (e.g., pagure).

However , @p.boy @darknao , I just saw that the “7-steps guide” button has disappeared and is no longer shown on any page. I guess that we have “killed” the button when we merged the HowTo’s update because the name of the adoc file has changed (it is no longer a 7-steps guide).

1 Like

Yes, that link needs to be changed in Antora’s playbook.

How I can clear my local fork completely?

If I have pending merge request and I love my local fork, will it affect future merges?

If you click on “create branch”, it will only add the new F37 branch and not touch the old ones. I don’t see how this should affect your other branches or existing merge requests.

So after creating the new F37 branch in your fork, you will be able to make merge requests against F37. And because you do not have the F37 branch at the moment, we can exclude that there are open F37-related MR that would be affected. So no worries :slight_smile:

When it comes to updating existing branches (which does not affect you at the moment) with newer commits (e.g., if MR from other users have been merged), we have to check if GitLab’s UI has already features that enable users to do that easily with one click. However, in the latter case, if there are open MR, the fork would need to update anyway before any contained MR can be merged. So the update of the branch would make any open MR “mergable” again. At the moment, I am confident that the GitLab UI behaves comparable in the case of updating existing branches (implying you do not need to worry about losing your contributions), but I will check this more deeply in the next days.

Generally: a merge can only happen if the branches are compatible to each other. This means that you need to have the same branch in the original repo and your fork (your current issue), and both branches (from the original + fork) need to be synchronized except for the changes made by the MR itself (the other issue we have to consider in the HowTo).

Please accept my apology if I am asking too manuy trival questions. Please let me know if I should start a new thread, or read more background information first.

This is copied from https://gitlab.com/-/ide/project/sampsonfung/fedora-linux-sysadmin-guide/edit/f37/-/modules/system-administrators-guide/pages/kernel-module-driver-configuration/Working_with_the_GRUB_2_Boot_Loader.adoc , line 1 to line 18.

:experimental:
include::{partialsdir}/entities.adoc[]

[[ch-Working_with_the_GRUB_2_Boot_Loader]]
= Working with the GRUB 2 Boot Loader

[IMPORTANT]
====
**Editor’s Note**

_This guide is deprecated!_ Large parts of it are no longer current and it will not receive any updates. A series of shorter, topic-specific documentation will gradually replace it.
For additional information about Grub version 2 on Fedora see https://docs.fedoraproject.org/en-US/quick-docs/installing-grub2/[Bootloading with GRUB2].
====

{MAJOROSVER} is distributed with the GNU GRand Unified Boot loader (GRUB) version 2 boot loader, which allows the user to select an operating system or kernel to be loaded at system boot time. GRUB 2 also allows the user to pass arguments to the kernel.

[[sec-Introduction_to_GRUB_2]]
== Introduction to GRUB 2

Compared to what is actually visible in the Docs site: Working with the GRUB 2 Boot Loader :: Fedora Docs
The Editor’s Note section is not visible. Which I think it is very important to readers that Grub2 with BLS enabled since Fedora 30(?), most are not applicable to new installs already.

Hi Sampson,

It is always appreciated when people give feedback! Indeed, if there are
issues on Docs pages, the team can only tackle them if they know about
it. Given the many Fedora Docs pages, the team strongly relies on
readers to let them know. This is also a type of contribution as it
helps to improve the “product”. Therefore, no need to apologize :wink: But
thanks for letting us know.

In this case, it might be sufficient to let @pboy or @darknao know about
it to have a quick look (I am not involved at the moment), I guess you
do not need to open a dedicated topic.

I updated the HowTo with a NOTE box that explains this behavior and how to proceed: Commit c81293d6.
The Docs page should be updated in <1 hour. Feel free to let me know if this NOTE box reflects your needs.

I have not yet had time to check how the UI behaves if the branch already exists but does not contain all commits. I will check later and adjust the box to contain that information as well. Feel free to let me know if someone knows already how GitLab behaves in such cases.