[Development] Buddy group to help new contributors

Sat Dec 9 15:21:04 CET 2023

Hi Volker and other interested readers,

I do agree with most of what you said. It is unrealistic to switch out 
the current platform tomorrow. This would be a multi year process.

    Wiki

In the current state the wiki is a mix of outdated and redundant 
information. We had a great success with mkdocs (or readthedocs) as a 
replacement for our internal mediawiki. The search of these wikis is so 
much better. In addition it is easy to start a quick MR/PR and fix the 
docs. IMHO as a programmer a simple git repo that I can build locally 
with one command, is easier to work with.

    Getting Qt running (on Windows)

Removing perl entirely would be nice. Python is a requirement anyway, so 
it would be easy to rewrite the script with python3. This my experience 
with perl on Windows setting up Qt:

 1. Started by searching online for relevant documentation and deciding
    to use docs over wiki entries.
 2. Identified the necessary tools for the project: CMake, Ninja, Git,
    Python, and MSVC 2022. Already had these installed.
 3. Decided to skip setting environment variables, preferring to use an
    IDE for compilation.
 4. Noticed that Qt didn't have a |CMakePresets.json| file, so created
    one based on the 'screenplay' project.
 5. Examined options on the Qt Building Guide and realized the need to
    install Perl, especially for contributing to Qt version 6.6.
 6. Cloned the Qt repository using |git clone
    https://code.qt.io/qt/qt5.git qt6| and renamed the local folder to
    |qt6|.
 7. Ran |perl init-repository| to initialize the repository.
 8. Encountered issues with Perl paths and cmake configuration in Visual
    Studio Code.
 9. Experienced errors with cmake and Perl's |ld.exe|, which led to
    frustration with Perl.
10. Found an issue on GitHub related to the problem.
11. Decided to remove Perl from the PATH and restart VSCode to resolve
    the issue.
12. Encountered a new problem with Perl 5.38 not working due to locale
    issues.
13. Resolved the issue by downgrading to an older version of Perl (5.32.1).
14. Realized the need to set the |--codereview-username| for Qt
    contributions. So delete the Qt source folder and start again.

This took like more than an hour of troubleshooting.

Now setting up gerrit:

 1. Tweaked SSH config as per instructions on the Qt wiki.
      * Encountered confusion with Windows path conventions and the
        absence of a default |.ssh/config| file. Used 7-zip GUI to
        bypass filename restrictions.
 2. Generated an SSH key pair for authentication.
      * Faced issues with the command's file path syntax being
        Unix-specific. Adjusted for Windows and successfully generated
        the key.
 3. Copied the public SSH key to the clipboard and added it to the Qt
    project's Gerrit SSH Keys settings.
      * Successfully verified SSH connection to the Qt project's Gerrit
        server.
 4. Attempted to use recommended Git settings.
      * Reluctant to enable |core.autocrlf| globally due to potential
        conflicts with other projects.
 5. Obtained the source code for the desired Qt project and made changes
    to the code and committed them locally.
 6. Tried pushing changes using Gerrit.
      * Initially used the wrong repository, leading to a "no new
        changes" error. Realized the need to push to a submodule
        specific to the changes (|qtdeclarative|).
 7. Successfully pushed changes to the |qtdeclarative| submodule on Gerrit.
      * Encountered uncertainty about the next steps, particularly
        regarding the review process and seeking attention for the
        changes on various platforms.

So this took  me about 1 hour of googleing. Keep in mind if you know 
this setup for 10 years you will not have this issue for newcomers it is 
hell. With git/hub/lab/ea it is fork->clone->push->create mr.

This could all be fixed in two steps:

      1. The git submodule system Qt uses.

A mono repo would be best. If there is an argue about repo clone size, 
lets just use git clone --depth 1. In the end the wiki tells you to 
clone all the modules anyway, so whats the point?

      2. Lets use CMakePresets.json

So the workflow is to load/unload sub repos and then check in the main 
CMakeLists.txt if the CMakeLists.txt file in the sub dir exists. If we 
find the submodule then we build it. This could be way better handled 
with a CMakePresets.json. o3de, formerly known as Amazon lumberyard, 
(formerly known as CryEngine) uses them quite extensively for every 
platform <https://github.com/o3de/o3de/tree/development/cmake/Platform>. 
Then in combination with user presets, one could create a preset for 
every main Qt module like do you want to build qml gui stuff? Here is a 
preset that enables all needed modules. This way you would not have to 
load/unload modules all the time. You can inherit from other presets to 
enable test etc.

    Other contributing tools

I checked about comment on commit and found some open issues on the 
Gitlab issue tracker. This is weird because I totally can comment on 
commit in GitLab, see my test comment here from my last merge request. 
When you go to a commit and scroll all the way down you can enter a 
comment 
<https://gitlab.com/kelteseth/ScreenPlay/-/commit/5c960b94a0049a74eafed79b62199bd95767fa52?merge_request_iid=108>. 
Then it will be displayed on the merge request 
<https://gitlab.com/kelteseth/ScreenPlay/-/commit/5c960b94a0049a74eafed79b62199bd95767fa52#note_1687350487>. 
I would totally understand when you say that Gitlab is too pricey. We 
also had to deal with their recent pricing shenanigans.

Sorry for the long reply,

Cheers 👋

Eli

On 12/8/2023 11:55 PM, Volker Hilsheimer wrote:
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20231209/17f5fc18/attachment-0001.htm>