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

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.

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.

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?)

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?

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?)

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.

Screenshot_20230220_134411b

1 Like

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.

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.

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…

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:

1 Like

Wow! That’s great news!! In that case it might be worth to wait before
putting more efforts in this :slight_smile:

If I find a free minute in the next days, I add a box to inform users to
keep an open eye if they have already a fork and that the issue could be
solved soon (to avoid that they waste time), just as interim solution,
and then let’s hope that 15.10. solves our issue.

1 Like

Very timely indeed. :clap: :clap: :clap:
Thanks for your heads-up (@py0xc3 @mattdm ).

I’m a half-convert to the new WebIDE when working with GitLab Docs repo. I have made two MRs using WebIDE today. I’m getting used to it.

We expect to see more users joining the casual contributor workflow.

1 Like

I have added a CAUTION box as interim solution. Hopefully, we can delete it soon :smiley:

Commits 8d4ac50c, 01ee8b70, e63d16cb

Source: modules/ROOT/pages/contributing-docs/tools-gitlab-howto.adoc · main · fedora / Fedora Docs / Community and Tools Documentation / Documentation Contributors Guide · GitLab

The published page should be updated in <1 hour.

Hank already identified that the feature was shifted to the 15.11 release, which is to be released tomorrow:
Fetch new upstream contents when fork is behind (#330243) · Issues · GitLab.org / GitLab · GitLab (updated)
15.11 · GitLab.org · GitLab

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

3 Likes

Sync button not visible in Web IDE beta mode. Until it is activated (maybe 16.0) and we get hands on with the UI and behavior, could we withhold any update on the casual contribution page?

The UI shows how far a fork is behind. But explanation on fork could scare target user groups @py0xc3 had in mind when the original guide was published in 2022.

@py0xc3 what compromise do we need for intended target group? Also you fear the revised procedure step 3 “create a branch” would lead to resignation of contributors. I admit I work on test pilot mode (beta tester) way too long without any feedback from your intended group and users you interacted in Discussion. Please advise.

1 Like

Indeed, originally, they just changed the topic that it has been released. I absolutely agree on your point that adding more stuff about how to update themselves could be scaring for the targeted users. It becomes more and more they have to understand and to get into…

My fear was, on one hand, that more steps leads more people to refrain from contributing because we wrote the guide originally for people who did not want to deeply get into git but just get their contribution done (this does not imply that this is still the major user group).

On the other hand, if we try to find new compromises that maybe go in other directions than the previous incentives from users, we should involve the community to get incentives (or let least offer the possibility to avoid exclusion- and misunderstanding-based defiance). So what I had in mind was that people gave incentives, and if then something else is implemented, this can lead to some resignation for giving incentives in future if we do not let people know about the “why we do that”. Additionally, inclusion through explaining the “why” might cause more incentives about how to proceed best from the user perspectives.

So this does not mean that your changes are wrong (they definitely fit the current GitLab better than my original version!), and we obviously need to add steps now, but that we should try to involve the people who work with it. We might not reach all, but some, and they maybe have some incentives about how to proceed with the current GitLab circumstances. I guess people who reject from any contribution on Fedora discussions are also unlikely to actively contribute in Docs. We can only try to propagate discussions on our channels.

There are no doubts that at the moment, there is no chance but to find “bad compromises” with the current GitLab UI. So if there is some interest from people who use the guide regularly (maybe @sampsonf ?) we could maybe start by asking them questions like:
→ with the updated guide that shall balance parts of the issues in GitLab, do you prefer to just get contributions done as quick and easy as possible, or do you also use the guide to get understandings of git? (e.g., implement best practices with adding steps to get your own branch). Or both?
→ what solution would you prefer for the current circumstances of GitLab? I think we have currently these opportunities (feel free to add more ideas!):

  1. each time remove the old fork - maybe easiest because it does not need much understanding, but it maybe feels a little destructive and does avoid to deepen understanding of git
  2. if your fork branch is not up to date, you can see it, and we can tell you how to update - definitely the best practice, but might be confusing and deterring for people who are not interested in getting deep into git
  3. Find a way to avoid forking at all because the above means take too much of time.
  4. Based upon the current guide, what are your general suggestions for further developing the guide? Feel free to also add related ideas if you have complementary thoughts about how to create a process that avoids/tackles outdated branches (for those who have related experiences). This is a little two-sided since we are asking people who use the guide, but at the same time we ask anyone with gitlab experience for ideas about how to mitigate the current UI issues the simplest way.

If that is ok for your @hankuoffroad , we could create a new topic so that people in the forums see that we ask for help in this respect. If you want, I can open it later today or tomorrow, but you can also open it yourself if you want. We can then put all points together.

The other points you made in the GitLab ticket are also reasonable and maybe things have a little changed, and especially in the current circumstances, it is possible that we need to focus on those who have some interest in getting into git.

I know this is also a bit a tautology, but finally we have no chance but defining the target group by those who respond and say “hey I use it, this is what I would like”, with the assumption that those not answering are also unlikely to do much contributions.

Btw, an addition could be to add a INFO box to the top of the guide to let people know that we currently seek incentives? So with a link to the new topic if we create one?

(Supplement for those who keep watching the AI topic: this post is not AI generated, I promise :smile: )

No, not at all. It is worth discussing before making a move or suggesting a change.

Could you create a new thread to engage with Web IDE users based on your questions?

Of course

The follow-up topic is:

Long-awaited update fork button in GitLab is here with 15.11 release on 22 April.

I checked it on 24 April today while I was working on my fork. See screenshot below.

  • If your fork is behind upstream, you will see UI text how far your fork is behind.
  • Click update fork button
  • The fork will display “Up to date with the upstream repository”
  • Fork button disappears after fork is updated

1 Like