To avoid the last topic to petter out even more, I open a new one about the issue of the new Web-UI and our casual contribution HowTo.
With regards to our GitLab HowTo for casual contributions, I identified a problem when I tested it the last time:
GitLab does not update existing repository forks, and it does not warn the user from it. This can be problematic because it does not only cause trouble or confusion to casual contributors, it can also lead them to do their contribution (=invest their time) without being aware, and then later find out that their work cannot be merged because they worked on obsolete files. This can be deterring in both respects, and create incentives to not contribute again.
Additionally, given the limited number of permanent members of Docs, I think keeping them occupied by handling user forks should be avoided (be aware that a short rebase is not sufficient if a file in the merge request does reference an obsolete version of the file in the target repo).
What does happen?
If contributors have forked a repository already during a previous contribution and then, at a later time, click on a related Docs page of the same repository on the “edit” button, then this contributor will end up at the related page in their fork.
So far, this is intended. However, the GitLab UI does not check if the user’s fork is up to date. If there have been changes / merges since the user has forked, the forwarding will still lead to the obsolete file without a warning/message (this happens even if the very file has been already changed). Maybe users see that the file they end up is not equal to what they wanted to change and are confused, or maybe they do not see it and keep working in the obsolete file.
This problem appears IF a repository has been forked before AND IF the fork is outdated AND IF the affected branch already exists in the fork (if the whole branch does not exist, GitLab will warn and allow to easily add the branch, which is already considered in our HowTo).
What do we need?
My suggestion would be to adjust the HowTo at the point where the “fork” button appears: IF the fork button appears, everything is fine and users can follow the HowTo as it is. But IF the fork button does not appear, the user seems to already have the repository and then, it is necessary to check if the user’s repository is up to date.
My preference would be to implement that by another NOTE box or something like that, at the best only with reference to a GitLab page that explains how to update the fork: the HowTo is already very long and this on itself can be deterring for contributors when they open this HowTo and see the vast information for a simple contribution. However, I have not had time to identify if there is a help page that contains explanations suitable for people without git experience. Also, I have not had time to check what is the easiest way to update a fork. At the worst, I will fix the issue later but I do not know when I have time for it, so I open the topic here so that you can already discuss and if you want, already work on the issue.
To Do list:
- find out the easiest way to update a fork
- find out if there is already a suitable explanation which we can link and that is suitable for people without git experience
- if there is no suitable explanation which we can link, author something (my suggestion would be a separated page, but feel free to discuss! Nothing is decided yet!)
- add the note box to the HowTo: IF the fork button does not appear, then check if your fork is up to date and if not, update it. I suggest to only adjust the existing box that begins with
The "Fork" button appears only the first time you contribute to the repository of a given Docs page. If you ...to consider the issue. (Or does someone suggest something else than a note box?)
Nothing is fixed, feel free to discuss, and pick up some of the tasks if you have time.
I guess this would be also a good first issue: Fix casual contribution HowTo: Add how to identify if existing fork is outdated + how to update existing forks (#16) · Issues · fedora / Fedora Docs / Community and Tools Documentation / Documentation Contributors Guide · GitLab
Casual Contribution HowTo GitLab source: modules/ROOT/pages/contributing-docs/tools-gitlab-howto.adoc · main · fedora / Fedora Docs / Community and Tools Documentation / Documentation Contributors Guide · GitLab