Skills building sharing and good practice collection

[marekgluza]

A proposal to have zoom meetings where we present good practice advice:

• We should expect that we continually will have newcomers who are learning from scratch about the qibo repos ("put this notebook in the tutorials repo so it doesn't create inertia in the main qibo repo", "the quantum_info module might have this functionality", "qibojit takes 20s to start") and guidelines ("we don't review before tests are passing", "we use pytest and the entire code should be covered", "have a separate repo which allows to reproduce the full running data"). These meetings would give newcomers space to ask questions but for shy people by listening to what others learned their unasked questions would be answered.
• Microsoft encourages recording video presentations about newly available features. I'm not suggesting that but improvised presentations how to run new code dev branches could help others be updated. This can speed up review later.
• As we are working we get new experience which others might not know. If we share it more broadly others might add on top of that i.e. 1 insight might lead to 10.

Questions:

• how often to have such meetings?
• how to make it self organized? (A naturally visible space where topic prompts are stored and attaching to the regular qibo meeting slot timing which already collects people?)

[alecandido]

• We should expect that we continually will have newcomers who are learning from scratch about the qibo repos ("put this notebook in the tutorials repo so it doesn't create inertia in the main qibo repo", "the quantum_info module might have this functionality", "qibojit takes 20s to start") and guidelines ("we don't review before tests are passing", "we use pytest and the entire code should be covered", "have a separate repo which allows to reproduce the full running data"). These meetings would give newcomers space to ask questions but for shy people by listening to what others learned their unasked questions would be answered.

To some extent, all of these should be part of the contribution guidelines, that should be maintained in each repo.
There is a standard format for that, as a CONTIBRUTING or a CONTRIBUTING.md file.
https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

This advice would be useful for anyone who wants to contribute something to the public Qibo project (and any of its repos), not only people that are starting in a position that is kind of related to it.
The files themselves should only summarize the main points, but they could reference external resources (foremost, the online docs).

Microsoft encourages recording video presentations about newly available features. I'm not suggesting that but improvised presentations how to run new code dev branches could help others be updated. This can speed up review later.

Well, we'd need much more manpower to regularly prepare proper video tutorials. However, whenever there are relevant user-facing updates, I'd suggest describing them during the Qibo meetings, even preparing short presentations in advance. For major announcements, we already organized dedicated meetings in the past (Qibolab 0.2, qibo-core, Qiboml, ...).

As we are working we get new experience which others might not know. If we share it more broadly others might add on top of that i.e. 1 insight might lead to 10.

That's definitely true. And it should be more or less the purpose of the Qibo meeting.
In case it's not optimal for this, I'd suggest reconsidering its structure (how we do it, but even possible to break it in multiple meetings, if convenient).

[alecandido]

Proposed topics for sharing should be stored as
wiki in qibo

If qibo had a wiki, since it would be public (as the repo) it should contain information for every Qibo user, not developers. But we already have the online docs for this purpose, I'd rather not duplicate them.

by adding a comment in a pinned qibo issue and you subscribe by assigning yourself

Issues should be dedicated to bug reporting and feature requests.
For the time being, we're not making much use of Discussions, so it's also acceptable to ask for help there.
Eventually, if someone just needs some help, or wants to trigger a general discussion, Discussions should be the place to go.

But I'd say that neither of them should be the place to systematically share knowledge.

separate repo

Viable option.

separate repo for a) github and python skills, b) quantum info/computing skills + c) existing tutorials repo

This for me is more or less the same of the former: a) and b) are available in many other locations, so it's not essential for us to start writing in-depth guides about them.
Instead, c) is the part specific to Qibo, and that's why we have https://github.com/qiboteam/tutorials/, for which I would encourage contributions.

The reason why tutorials are not very extended is that everyone is pretty busy developing and maintaining many features across one or multiple modules, which description will(/should) be provided in the related docs. So, you would first have to write it in the docs, then also take the time to write a tutorial.
This is usually not happening, because of lack of manpower.
However, a more viable approach would be to encourage new joiners to contribute these tutorials while learning about the Qibo features (either from the docs or discussions with other team members).

For the developer/physics skills part, we could have an internal repo with references (that I'd keep private for internal education, and light, such as useful references are provided, but we don't need to make an effort to maintain it updated).

[marekgluza]

@alecandido @scarrazza moderation question: Should we keep an open thoughts discussion for now or close the call for suggestions and move to deciding how to proceed?

A good format would be advisable for onboarding e.g. the CQT intern or the newly active Quantum Spain collaborators

[scarrazza]

@marekgluza, could you please raise this issue during the next Qibo meeting?
I would like to see more than a single vote before closing this poll.

[andrea-pasquale]

Personally, as @alecandido said I think that for the time being having a CONTRIBUTING.md file would be more than enough.
In particular, such file should include a series of prerequisites that the user should be comfortable with before contributing including: git, pytest, coverage, poetry and so on. For those prerequisites there are already huge resources which are only a google search away, this is why I don't see a point in having those type of meetings. For specific problems we can always discuss in issue or PRs.
Moreover, with the current manpower I doubt that it would be possible to have this type of meetings often.

[marekgluza]

Today:

• there was a point saying some information is not related to qibo but general technical skills. Question to @alecandido and @scarrazza - can the overarching info be added in qibo.science? Then it would be a platform for the community building for qiboteam as opposed just pinning everything to the qibo repo (which I think is clear nobody wants). More specifically: can there be a wiki on qibo.science?
• Ale said "best get in touch". Can core devs comment on what precisely is the protocol for getting in touch?
• matrix was mentioned but in practice there might be exchanges on telegram. What should be the quick access chatting options for a contributor who joins completely from outside?
• it was mentioned some information would be hidden. Who would be decide who gets access to that?

As I understand a sketch of proposed solution could be

1. CONTRIBUTING.md file which contains:

• for begginners a list of expected technical skills which are used by qiboteam and should be learned individually through widely available sources (github, pip, poetry, pytest, pull requests, code review, test coverage, key outside packages, advanced technical packages with which the code must remain compatible, PEP source code formatting conventions, advanced python coding which goes beyond 1 semester of python coding at uni e.g. dataclass, extensive use of call, abstract classess instantiated through backends, math eqs in docstrings must be ready to parse in the docs).
• for advanced coders a set of physics skills which are needed to understand the code but are available in e.g. Nielsen Chuang
• guidelines step by step how to contribute
• guidelines and contact channels inviting people to discuss

2. Wiki (somewhere) with useful know hows e.g.

• pip install -e. is not something physicists learn in their courses and might not even know how to google that this is how to use the dev branches of qibo
• poetry commands
• precommit

Comments on my side:

• my first encounter with Qibo was talking to Paul and I didn't want to bother him so for half a year I ended up not contributing at all. What could be an alternative solution to the scenario where someone can contribute but needs onboarding? It was not clear at all for me what would be the steps I'd need to do or if I could get the qibo dev help to add a feature.
• For half a year I didn't do anything until Stefano assigned team members and we started working. What worked well but would not be a universal solution is that they coded the porting of my code into qibo and then I learned how my code which I understand functions in qibo. Would it be possible to assign more experience qibo devs to mentor incoming people e.g. a contact person who then points to necessary resources?
• to me the discussion here is not so much about efficiency but about community building. Qiboteam operates via a certain culture which can be very attractive to e.g. physicists joining in but can there be a suggested way of onboarding newcomers?
• one of the biggest roadblocks for a newcomer to contribute is to know how to and to know how to get help - if it's not clear they will usually choose not to take action and the collaboration looses an opportunity to benefit from momentum. Instead if there is a streamlined workflow how to enter the contributions that pass different checkpoints can benefit the collaborative efforts

[marekgluza]

I almost agree: I would list some technology (i.e. poetry and pytest), but rather in the contribution guidelines in the online docs, i.e. here:
https://qibo.science/qibo/stable/developer-guides/index.html

Could this be added to the default issue and pr text? The current PR fills in the review and test checkboxes etc All of them could give the link to these guidelines maybe?

[marekgluza]

That's the main reason to have a public chat. To engage with newcomers.

Can we run some experiments with people who don't know qibo how they navigate? For example they will go to qibo.science will they find the relevant information intuitively.

Once they find the matrix link will they be able to say: "hi I want to contribute but I have a question" and will someone respond?

The motivation for saying this is that there was a person coming from outside #1358
and there was no welcome message.
Above you say that so far there were few people so most interactions happened in person. But how can it be more if there is no workflow to welcome remote contributors and give them the orientation on the process?

[alecandido]

I actually thought it was discontinued because I searched for it on a new laptop and then couldn't find it.
It could be hard to realize that the graphic button is the link. It used to be explicitly provided and maybe it could get more visibility that way?

I believe it has always been that way (I guess because the "shield" is directly provided by Matrix itself), but we could also add an explicit link (with or without explicit URL).

For Matrix, several people I pointed to it and they were confused what it is and then how it is structured. For example there are many ways to access it etc At least for me, I remember that when I first entered it seemed like an empty space and it wasn't clear how to write to somebody. Shouldn't there be some default 'room' or something #general channel like on slack?

In the Qibo workspace, there is a unique public channel, called "Community". It is not called "#general", but that's the sense.
I guess the main issue is that people are already used to Slack, because they pay the price of learning it before (the first time I opened Slack, I had the exact same sensation - I had to found where things were, because it was not like Skype, WhatsApp, Telegram, MSN, Facebook Messenger, ...). It's definitely new for many, but it's free (as free beer) and self-hostable (so, definitely even as free speech).

There is a more or less default application, which is Element, but you could appreciate even other clients (Gnome has its own native one), as many appreciate the variety of email clients (and many others use the web apps provided by their host 🤷)

[alecandido]

Could this be added to the default issue and pr text? The current PR fills in the review and test checkboxes etc All of them could give the link to these guidelines maybe?

Possible, but I'd rather write it in the README :)

[alecandido]

Can we run some experiments with people who don't know qibo how they navigate? For example they will go to qibo.science will they find the relevant information intuitively.

We can, but essentially that's what we do with every newcomer. And we try to learn something every time.
Doing it on purpose would require an explicit supply of newcomers, and dedicated time and effort. And things are moving anyhow, so I suppose that doing it continuously should be more effective (true that there is no one assigned to the task, so it could be easily neglected - but we would need someone to volunteer for this responsibility...)