[Development] Buddy group to help new contributors

Fri Dec 8 23:55:00 CET 2023

Hi Elias,

Thanks for taking the time to share your input to this! See comments inline.

> On 8 Dec 2023, at 15:33, Elias Steurer via Development <development at qt-project.org> wrote:
> 
> Hi Volker,
> Thanks for the update on the Qt Contributors Summit. It's great to hear about the initiatives to make the contribution process smoother, especially for newcomers.
> However, while setting up a Gerrit group for hand-holding new contributors is a step in the right direction, I believe we might be missing a crucial point. The core issue isn't just about guiding new contributors through the existing process; it's about the inherent complexity and user-unfriendliness of the current workflow.

On the positive side, these things are not mutually exclusive: we can improve the process and the documentation while providing a better welcome-experience and support for new people that want to contribute, but struggle with what we have. In fact, I’d claim that hand-holding people through some personal contact is always going to be a good idea, even if Qt would be a simple code base that anyone could build, write tests for, and make fixes in without having to learn anything new.

> From installing a plethora of tools to dealing with the confusing repo cloning process, Perl dependencies and Perl path issues,  the barriers to entry are high.

Yes, setting up a local development environment that can build Qt is not trivial, esp if you want to build all submodules, and want to work on Windows on the one hand, but on the other hand want to use something other than the native compiler and SDK for that platform ;) And if you want to make sure that your code compiles and that tests pass with your modifications just on the main desktop platforms, then you’ll be busy setting things up for a while.

There is certainly room for improvement, but I think the complexity is a bit in the nature of the beast as well (that beast being not just Qt, but C++, several development platforms, even more cross-compile targets etc).
Can we make that fundamentally easier? Should that be our goal and what we spend our time on? Would it make a huge difference if we didn’t require perl (and IIRC we only need it for the init-repository script)? You need cmake, ninja, and your compiler and platform-specific SDK (which is mostly trivial on Windows and macOS; on Linux it’s a bit of a piece-meal). But none of that strikes me as particular esoteric stuff. Well, unless you want to build webengine, or check all the SQL-driver boxes.

Anyway, if you can make specific suggestions on how we can improve the build system of Qt and reduce dependencies to tools or libraries, then please do so.

> Then, there's the challenge of navigating the Gerrit setup, which is far from straightforward. The documentation is inconsistent and sometimes contradictory, adding to the confusion. And that's before even getting into the complexities of submitting patches and managing code reviews. If you want I can send you my personal notes, that I have written down recently while setting up Qt locally for the first time in years. Most of it is about my frustration why a solved problem, like contributing to an open source project, is so unnecessary complicated.
> In essence, the current workflow is daunting, even with a support group. I suggest we consider moving towards a more streamlined and "sane" workflow. Simplifying the entire contribution process from the ground up will make Qt more accessible to everyone. Once a more intuitive and welcoming workflow is establish, guiding new contributors will be much more effective. After all, the best hand-holding is the one you don't need because the path is clear and easy to follow. 

If step one has to be that we simplify the entire contribution process from the ground up, then this will get us exactly nowhere any time soon. This is not only because there is a variety of differences in the Qt project contributor community about what we should optimize for. Many of us consider gerrit’s code review user experience vastly superior to github’s or gitlabs; many of us believe that the history of a patch is a critical piece of data that is easily lost, or hard to find, in the github/lab workflow. I don’t know if it’s possible by now to comment on the commit message in github/lib/ea (it wasn’t last time I checked), but not being able to do so would be a total showstopper for me personally, and I don’t understand how projects that care about their git history can function if reviewers cannot give structured feedback to the most important part of any change, esp to new people.

So building consensus of what “simplification” means in practice is going to take a while.

But even if by Christmas we all agreed that we should move things to github/lab/ea, it will take a significant investment of time and money to actually make that move. There exists a significant amount of tooling, process automation, authentication structure etc that is based on the setup that we have. From a variety of bots to CI integration and other test automation, to releasing and packaging. That’s a ton of work to replace.

We can start the discussion and identify some specific improvements that move us forward, and maybe even end up agreeing what the perfect workflow would look like; but waiting for the grand simplification to arrive before we do anything is IMHO not the answer.

> It might be worth considering a migration to GitLab, which has been a successful move for other open-source projects like KDE and Arch. Given that Qt already uses an internal GitLab instance, this could be a good platform for future collaboration. Alternatively, adopting Gitea, as used by the Blender Foundation, could also be a viable option if Gitlab licensing is a no-go. 
> I strongly believe the focus should be on overhauling the workflow first. Everything else, including smoother onboarding of new contributors, will naturally follow.

See above. Even if I would believe that there's a magical greener pasture for *everyone* (not just for new contributors; we can’t optimise the process for that group of people if it makes the process harder for people doing the vast majority of the work, esp for the maintainers and reviewers), getting there will take more time than we should wait.

> There was also an discussion about this recently on Reddit.

Reading through that, it's a mix of

* I’m not willing to sign the CLA (can’t help you buddy)
* I couldn’t find a reviewer (that’s exactly what the buddy group is going to help with)
* “I’m not going to learn a workflow that is not github” - sorry, but “shrug”; I have no reason to believe that you will be willing to learn what it takes to make your patch work on a platform you are not familiar with
* and yes, a few statements that the process is hard - with some encouraging statement from Psychological_Ad1417 that by getting help, it isn't so difficult (and 

So, of the four main sentiments that I can identify in that discussion, two can be addressed to some degree by a buddy group that proactively reaches out to lower the learning curve.

Volker

> On 12/5/2023 9:57 AM, Volker Hilsheimer via Development wrote:
>> At the Qt Contributors Summit in Berlin last week, we discussed various ideas around improving the contribution experience, esp for new people.
>> 
>> One action that came out of that was setting up a gerrit group of people that are able and willing to hand-hold new contributors through the process. This includes setting up your local development environment, gerrit configuration and workflow, and finding out what to work on from e.g. Jira. The basic idea is that we establish a (gerrit, probably) group with buddies; we can already identify “first gerrit reviews" for a new user, and then we can proactively reach out with a welcome message, and add the group of buddies as a reviewer.
>> 
>> A few people raised their hand at the event, but I don’t think anyone took down the names, and I was busy juggling microphones. And either way, this is of course open to anyone! So please reply to this, either to all or privately to me, if you want to be part of that group.
>> 
>> Cheers,
>> Volker
>> 
>> 
> -- 
> Development mailing list
> Development at qt-project.org
> https://lists.qt-project.org/listinfo/development