Sketching ideas for the content of a Community Handbook

[sgibson91]

One deliverable of the Community Strategic Lead grant (#536) is a community handbook. This issue is serving a "sketchpad" of sorts for the content of such a handbook based on my own observations, hallway track conversations I've had with various Jovyans, and the outcomes of the member research (#571) when that kicks off. These "sketches" will probably spin out into their own issues as they shape up. Please feel free to contribute your own!

My aim with the handbook (at time of writing, scope can expand to beyond processes of course) is as follows:

1. Document implicit processes and make them explicit
2. Iterate on these processes to improve them/make them functional

Step 1 is super important because we can't do step 2 without it, and newcomers will feel more welcome and confident contributing because they also don't have to pick up a lot of undocumented/unknown cultural practices that you have to somehow "figure out".

[sgibson91]

Merge and Review Policy

I had a few sidebar chats with folks I had been working where they were asking questions like "Who do can I request a review from for this?" and "Can I push the merge button? When?"

To my knowledge, we don't have an explicit merge and review policy. The closest I found was this from the Littlest JupyterHub repo, but I think that covers more "How do I prep my PR to be reviewed?" rather than some of the etiquette-based questions I had been asked. However, I love the "Have Empathy" section!

I think we should try to scope a merge and review policy. As a first draft, it should be "what we do currently", and then we iterate as we feel it serves the team. For reference, here is 2i2c's merge and review policy: https://team-compass.2i2c.org/en/latest/infrastructure/reviewing.html Also, I believe it should be explicit that for any repo that already has an established policy, that policy takes precedence over what we define centrally. The maintainers who developed that particular policy should retain the right to opt into this centralised one. Similarly, any new and existing repos without a policy should be able bootstrap the centralised policy.

Resources

1. https://www.morling.dev/blog/the-code-review-pyramid/

[manics]

Related issues on the PR workflow:

• Guidelines regarding self-merging PRs #466
• Recommend (or require?) PR workflow for contributing to repositories #465

[sgibson91]

Labelling conventions

This arose through a conversation with @GeorgianaElena and I invite her to provide her own perspective here.

I think labels just get messy when you're a multi-repo-spanning, org-based project 😂 and that is ok to some extent. If we are going to rely on labels for categorising/signal boosting issues and PRs though, it may be useful to define a "core set" for the org and document their meaning and purpose. E.g., it was unclear what the needs: revision label in the jupyterhub repo meant. Does it need another review, or does it mean the PR author needs to change something?

This will be opinionated and have variations based on the workflows of a given repo, so there may not be a lot that is useful here beyond the bug, needs: review style labels in a "core set". Perhaps instead a process documenting:

1. When to create a new label,
2. Defining "is it an org-wide label or a repo-specific label?, and
3. Where best to document that new label so it makes sense for other people.

Again, we shouldn't override any repo that already has an established label-based workflow. Any repo can opt in to a "core set" and add their own as required.

[betatim]

We also have https://repo2docker.readthedocs.io/en/latest/contributing/contributing.html#guidelines-to-getting-a-pull-request-merged, which is more aimed at making contributions/contributors. Previous versions of this text also contained some sentences on self merging PRs. I think the content here is mostly aimed at contributors, not maintainers.

Is the goal of the merge and review policy to give advice/instructions to reviewers or to contributors? I think the content and the level of technical detail is different for these two different groups.

[choldgraf]

A suggestion from me: I think it's also important to distinguish between what is policy and what is guidance. We probably want our policy to be fairly lightweight, and focused on the most important principles and actions to take. Our "guidance and recommendations" can be more opinionated and verbose, and cover more workflows. But we should make it clear that there's a difference so that we don't create confusion about what people must do vs. what they may do.

[betatim]

These are not hard rules to be enforced by 🚓 but they are suggestions written by the repo2docker maintainers to help complete your contribution as smoothly as possible for both you and for them.

I am a big fan of this. I'm not sure what I'd even put in the "policy" category.

[sgibson91]

Ok, I picked the wrong word regarding "policy" - that's fine. I'm mostly using this thread as a replacement for all the sticky notes that litter my life regarding this kind of thinking than anything concrete right now 😄

While I find this really useful to organise my own thinking and removes the barrier of finding issues (I can usually find a pen and a sticky much quicker!), I realised it wasn't very collaborative - so I'm trying a different approach! These are generally really nascent, early formation thoughts - "sketches" - and still need moulding and shaping. We can hammer out details in iterative cycles.

[sgibson91]

Is the goal of the merge and review policy to give advice/instructions to reviewers or to contributors? I think the content and the level of technical detail is different for these two different groups.

I agree! This idea, for me, arose from a conversation with a new maintainer who didn't know the process. The fact that #466 exists indicates that we have an unwritten { policy | guideline } [delete as appropriate] around not self-merging. And that's someone with the ability to merge needs to know.

There's totally space for a "How do I start reviewing PRs/triaging issues for JupyterHub?" style guide that focuses on a contributor, maybe one who wants to be on the path to becoming a maintainer. Which leads me into my next "sketch" question of...

Do we have an onboarding guide?

[GeorgianaElena]

@sgibson91, I managed to dig out a prior discussion around issue labels. Maybe we can learn from it #334 ?

[GeorgianaElena]

Do we have an onboarding guide?

This PR from 3y ago: #167 and current state of the docs https://jupyterhub-team-compass.readthedocs.io/en/latest/team/adding-members.html#adding-and-onboarding-new-team-members

[sgibson91]

This PR from 3y ago: #167 and current state of the docs jupyterhub-team-compass.readthedocs.io/en/latest/team/adding-members.html#adding-and-onboarding-new-team-members

Thank you for finding those @GeorgianaElena! Those feel very team-focussed though? I'm thinking about all of the requests in my inbox from Outreachy applicants along the lines of "How do I start?" right now. How do we orient people to the project first of all, so that they can begin doing the kind of work that would make use consider onboarding them to the "team". Moving from "contributor" to "maintainer", or even just to become a "contributor", to use the parlance of our recent governance restructure.

[GeorgianaElena]

So, what this basically means is that we need a step in between, right?

My feeling is that the CONTRIBUTING.md file in each repo (eg. https://github.com/jupyterhub/jupyterhub/blob/main/CONTRIBUTING.md) could serve as a "starter kit" for people looking to contribute to a specific repository.

But then we also have people that want to get involve somehow and don't know where to start and often get confused by the terminology itself and how all the projects fit together (jupyter vs jupyterhub, single-user server vs notebook vs kernels, but wait, there's a lab also??). I believe these are the people that would benefit a lot from a more higher-level onboarding.

I personally believe that jupyterhub/jupyterhub#2726 has a LOT of useful information that could go into a general technical onboarding into the JupyterHub project. From there, we could then point people to project specific CONTRIBUTING.md guides, where different labels or merging policies could be listed? We could have org wide practices but also project wide ones.

Would something like this make sense?

[sgibson91]

@GeorgianaElena I love this idea!

But then we also have people that want to get involve somehow and don't know where to start and often get confused by the terminology itself and how all the projects fit together (jupyter vs jupyterhub, single-user server vs notebook vs kernels, but wait, there's a lab also??). I believe these are the people that would benefit a lot from a more higher-level onboarding.

Yes, I was thinking this as well. And maybe even how the modularity of JupyterHub (spawners, oauthenticators, etc) map onto our GitHub structure? You might know they thing you're looking for, how to find it?

[betatim]

For people new to the project there are (at least) two areas that are hard: how and where.

How: the mechanics of contributing/how do I contribute (how do I use GitHub, git, run tests, build docs, etc). I think for the generic things we should try and link out to other documentation/tutorials (roughly this category contains things that someone who is an experienced contributor to another project does not need to learn). For the project specific things we should have a short guide (things that someone from another project might not know, e.g. how exactly do you build the docs in binderhub?)

Where: I think this is much harder to help people with. A good place is "good new issue". It points you to something concrete to do. However where do people go from there? Ideally they'd have their own "problems" with the project that would generate ideas for where to work. However that isn't often the case. Reviewing other people's PRs is one of the hardest tasks to do as a newcomer (or anyone really). So I think we need a few more steps between "good first issue" and "help review other people's contributions".

From my own recent experience: I mostly have no questions about the "how" of contributing to scikit-learn. However I have no good idea of "where" to contribute (after doing a few "good first issues"). I assume it will take a while before I have enough "problems of my own with scikit-learn" that will then generate things to do. How to speed that up is something I'm thinking about, but have no good answer.

From my own (less) recent: people ask me where to contribute to a open-source project and I have no good answer for them other than "pick a project you are actively using and have a 'problem' with. Try and figure out how to fix that."

TL;DR: finding a good way to give people an idea of "where" to contribute that matches their level of skill and time commitment and is helpful for the project is hard. But somehow needed.

[manics]

Is attempting to reproduce reported bugs in GitHub issues something a new contributor can do? Or is that still too technical?

[minrk]

@manics it definitely is possible, though how feasible it is will depend very widely on what's involved in the issue -it may involve a specific authenticator or spawner they can't deploy, etc.

trying to recreate that environment for the repro case (even if they don't succeed) is a useful exercise in understanding how jupyterhub pieces fit together. It could be rather frustrating, though, especially if they ask for help after hours of effort only for someone more experienced to say "oh, you never had any hope of reproducing that, because you don't have X."