Problem in the casual contribution HowTo: contributors will not be warned if their fork is outdated but will be forwarded by gitlab to work in their obsolete fork

[py0xc3 (Chris)]

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

[hankuoffroad (hank)]

There is an option to refresh a fork using settings in your fork.

In GitLab, go to your fork, settings on left pane > repository > Expand ‘Mirroring repositories’ on the right > Add Git repository (upstream) URL > Mirror direction - Pull

Tick ‘mirror only protected branches’ : optional

For more details, please refer to the link.

Repository mirroring | GitLab

[sampsonf (Sampson Fung)]

How about delete the “fork” before fork again.

I hope it will be easier for beginners.

[py0xc3 (Chris)]

If we choose this possibility, we should test if the mirroring takes
place immediately or only at specific times. If a user had not activated
mirroring at the very time of forking, this might create inconveniences
if the user has to wait, or does not know about the need to wait and
starts working in obsolete files before the mirroring is triggered. We
would have to formulate our adjustment correspondingly.

[py0xc3 (Chris)]

That is indeed another possibility. If the mirroring of the alternative
is triggered immediately after activation, I think both of the two
possibilities are at least acceptable although not very nice for users.
But if the mirroring is triggered not immediately, I think deleting the
fork would be indeed easier for most users and avoids confusion.

[mattdm (Matthew Miller)]

The mirroring thing is a really daunting task for new users on Gitlab — it’s buried way too deeply in the settings. I wish there were just a brightly-colored “sync fork” button like Github has. Plus, what if there is now a conflict?

There was a previous doc that Ben wrote suggesting that people work on a new branch in their fork. That seems to me to eliminate a lot of the problem…

[hankuoffroad (hank)]

Deletion of the fork seems straightforward. Have you tried it?

I still have to navigate to settings and find out which options to expand.

Settings > General > Expand ‘Advanced’ (far down below) > Delete this project

This action deletes hanku.lee/documentation-contributors-guide and everything this project contains. There is no going back.

Are you absolutely sure?
You are about to delete this forked project containing:

0 issues
0 merge requests
0 forks
0 stars

This process deletes the project repository and all related resources.

Enter the following to confirm:
(copy your fork URL)

Yes, delete the project

[mattdm (Matthew Miller)]

I feel like that’s kind of scary too, but it does work.

I wish Gitlab had a flow to support this — one button “fork and edit in a new branch in the fork, and keep the original up-to-date”.

[mattdm (Matthew Miller)]

Oh, another thing to keep in mind — GitLab’s mirror / sync functionality is an “Ultimate” non-open source feature.

This means to get that, users need to either fork into something under the Fedora namespace (where we have those features under GitLab’s open source program), or have it some other way.

[hankuoffroad (hank)]

@sampsonf @py0xc3

I misguided you. And I was not supposed to suggest repository mirroring for the problem @py0xc3 identified. Mirror direction (push or pull) is greyed out, which means the feature is not included in the plan the Fedora project is granted.

[hankuoffroad (hank)]

@py0xc3 Could we use WebIDE even without having a fork at all if the page is devoted to casual contributors? I tried it after deleting my fork and the commit/push button appeared when committing changs.

(Edit: not sure what minimum permissions are required for committing changes without a fork)

We could just explain how to navigate to the page to edit and go to left pane and click source control (git merge logo) and commit and push. That’s not all.

Still, I am confronted with usual question on branching.

• Yes, commit to a new branch
• Use the current branch main - i went ahead with this, feeling guilty

Test to edit without a fork (1031599c) · Commits · fedora / Fedora Docs /...

If we impose a fork, then we need users to follow branching conventions, which will assume certain amount of knowledge around git source control.

Or is this anti-pattern in writing collaboration (there is no peer review and it is direct commit)?

There’s more - how to close WebIDE after commit? Just close the browser?

Need some explanations on key features of WebIDE UI - how to enable preview screen? We need to cover some obvious questions and user behavior. I don’t feel WebIDE is easier/efficient than git commands.

[sampsonf (Sampson Fung)]

It took me a while to find out how to list all of “my” projects.
(I do not expect a “fork” is actually “my project”, and I don’t even know it is a “project” in GitLabs eye)

Then I removed all Fedora Doc forks listed under my Gitlab account.

Thank you for sharing.

[py0xc3 (Chris)]

You are capable of working in the Docs repositories because you have
developer privileges. The users have to fork because developer
privileges are limited to permanent Docs members. Unfortunately, a lot
of possibilities to cause damage are in these privileges, so I think
giving anyone this possibility is not an option.

If users use the “edit” button on a given Docs page, they do not need to
choose a branch. They will be just forwarded to the very branch of the
page they are.

I agree that the new UI feels not appropriate; but at the moment, the
only alternative seems to switch to the traditional editor we discussed
as alternative earlier. However, with the new problem in mind, it would
be interesting to test how the traditional editor behaves: does it warn
the users if they are forwarded to obsolete forks / obsolete files? If
the traditional editor behaves different than the UI, this would be
indeed a reason to re-open this discussion. I will see if I can spare
some time to test this in the next days, but feel free to test it earlier.

“How to close git after commit?” → Yeah, we could add a note how to
logout or such. You are right that the end of the guide makes the reader
a bit feel alone with what to do next, not a best practice indeed.

“preview screen” → I don’t think that the new UI has a adoc-preview
screen, does it? The language that git is using for itself and which it
expects when creating a preview is not equal to adoc. But of course such
a feature would be nice. But maybe we could add a TIP box and link to
the repository template which elaborates in its README.md how to use the
preview scripts → however, before we can do that, we need to update all
repositories to contain the new scripts Ankur has written (not sure if
that has been already done?)

[hankuoffroad (hank)]

@py0xc3

If users use the “edit” button on a given Docs page, they do not need to
choose a branch. They will be just forwarded to the very branch of the
page they are.

OK, I’m better informed now.

Using a new Fedora account (klavier), I walked through the process in 7-steps-guide like for the first time user.

A clear warning is displayed

You can’t edit files directly in this project. Fork this project and submit a merge request with your changes.

Once fork is created, I have two options - WebIDE and edit. All clearly labelled and easy to follow through.

@py0xc3 is the thread concerning a paragraph below?

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 automatically 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.

About this thread (fork out of sync), I need to see if the fork is up to date with the upstream repository or not in next weeks. I’ll use WebIDE how I quickly get used to it. Then I’ll suggest a new wording for branching.

@sampsonf what’s your experience so far with WebIDE?

[sampsonf (Sampson Fung)]

I have Opt-Out of WebIDE - so far I only able to follow the 7-steps guide. (the 7-steps guide is not using WebIDE, right?)

[hankuoffroad (hank)]

The 7-steps guide shows WebIDE UI. You have an option to choose WebIDE or edit button

One thing that behave different to the guide is how ‘create MR button’ is triggered.

• Yes, commit to a new branch
• No, use the current branch ‘main’

I tried both options each and led to create MR button (and go to project) down below of the UI.

[py0xc3 (Chris)]

Hank,

Regarding your first post of today: No, it is not about this paragraph
→ This paragraph/note is about the lack of the whole branch: if the
branch is not yet existent, there is a warning and the users will be
able to easily solve the issue by clicking the button shown by the Web
UI. So this is not a big thing.

The problem of this thread is if the users already have the branch, but
the branch is not up to date. Then, it seems with the Web UI that the
users do not get a warning. I have not yet had time to check if the
traditional editor has the same issue.

Regarding your second post: Just to avoid confusions, the “edit” button
you can choose instead of the WebUI refers to the traditional editor I
meant.

[mattdm (Matthew Miller)]

Here’s a theoretical workflow idea. I don’t know how this could be implemented, just food for thought…

1. Each docs site would have a “casual contributions” fork.
   • This would be on gitlab, regardless of the “home” of the particular docs site’s choice
   • all branches that exist in the main/upstream repo would be synced automatically
2. A workflow button would create a new branch in that fork, not a new fork
   • this branch would be named after the account of the contributor, plus a number if a branch already exists with that name, plus a short name provided by the contributor describing the change
   • the contributor would get access to only that fork — all other branches would be read-only / protected
3. When the edit is done, the contributor would be asked if they want to make other edits related to the same thing or if they’re done
4. When done, a PR is created.
   • if the upstream repo is on gitlab, the PR would be against that repo directly (branch to main)
   • if the upstream is on github, pagure, gitea somewhere, whatever, it would be created against the “casual contributions” fork and a notification sent to the upstream team and/or the docs team

That way, the contributor never needs to deal with “owning” a fork at all.

[py0xc3 (Chris)]

That’s indeed an interesting approach, it could solve many issues. But
for such changes/approaches we have to involve @darknao since he will be
the one who has to do that type of work.

My assumption is that this would cause much work and I am not sure if
these efforts justify the amount of casual contribtuions we have (?). I
can only assess that to a limited extent atm.

However, the idea of having dedicated forks for casual contributions
would create possibilities to enable any FAS account for developer
privileges in the forks, without affecting the target repos. I think
this type of approach can be done with less automation (which also
implies less work for darknao), but it would mean that the team has
double as many repos to review regularly. Additionally, with this, we
would change the whole process: users would work within the fork and no
longer create MR but just commits. So this would disable possibilities
to have a common page to discuss on, except we encourage them to
additionally create tickets that elaborate their commits (which I
suggest to not do because it would create comparable complexities like
the current approach).

So, users could easily contribute and I guess we could achieve that just
by changing the links of the “edit” button (once we created the forks).
However, additionally, we would loose the possibility to discuss the
changes/commits at a common place (like the MR page), and thus, also
loose the possibility to explain users when we reject a change for
whatever reason (except writing an email or so, but I would not impose
that on the team). Additionally, the team would have to do the MR from
time to time. I guess the last point is the least issue, but the
remaining points mentioned before might impose too much active work on
the team (?). Because this is also a complete different approach, we
would need to rewrite the whole guide (but I guess if the approach works
out, it would be worth to do that).

I am unsure, but I tend to assume that the manual approaches I described
would maybe add too much complexity for the team, even if it would free
the casual contributors from some complexities (plus the issue of the
limited communication possibilities). This leads back to the question of
what can be implemented in an automated way without causing too much
work for darknao.

@darknao @pboy what do you think?

At the moment, we seem to have no acceptable approach for casual
contributions once a user has forked a repo before. My personal opinion
would be to first try to find other alternatives that impose less
changes on the team, but keep it as alternative in mind. Most worrying
is the current fact that a user might do work and finds out that it
cannot be merged just after finishing the work (at the worst, this user
will not contribute again: wasted time can be very daunting).

However, another manual-solution-like direction to think to (might be
easier for the team): we leave it as it is, and with the assumption that
a MR can be created even if the very file is obsoleted, one of the team
has to manually adjust the outcome (a TIP box might inform the users
that they have not to care for that). This would also cause work to the
team, but would not change the processes, and I could imagine that it
would not be more work than the above approaches.

The last solution would not solve the problem that the users might be
confused if the file already differs at places they want to change. This
would have to be solved by TIP and NOTE boxes (I know… more to read
for the users…), and in this one case, there would be no alternative
than leading them to updating or deleting their fork.

Just some directions…

[mattdm (Matthew Miller)]

Holllld the presses, everyone! Breaking news!

I went to look to see if there was an RFE or tracker bug for GitLab to add an easy “sync fork” button. Well, turns out there is one Fetch new upstream contents when fork is behind (#330243) · Issues · GitLab.org / GitLab · GitLab, and what’s more, it’s very far along, with the the work probably landing in the 15.10 release in a month.

From the prototype images: