Enhanced mentor support

[trallard]

Over at our last event, we realised that there were some nuances and particular challenges faced due to the online nature.

I would like to explore how we can better support mentoring teams. Some common issues folks run into sprints and on virtual sprints are:

• Setting the local environment
• Familiarising with the codebase
• Identifying issues
• Provide suggestions for tools for peer-coding

@Zac-HD creates a meta issue for sprints: https://github.com/HypothesisWorks/hypothesis/issues/2510 so maybe requesting this would make the onboarding easier This could be pinned or set as the Discord project's description

GitHub Codespaces is not yet available for the wider public but when this is it might be worth exploring this and encourage projects to use this to help with the local environment issues

Please add ideas and suggestions here

[trallard]

@pycon-mentored-sprints/organisers

[Zac-HD]

More of a general reflection than a suggestion: making a project accessible for new contributors is a hard UX problem.

For someone who isn't comfortable with git or Python dev tools, every single step is going to be slow and probably stressful... the best I've done is a cross-platform tox setup. Designing your build system to be used by absolute beginners with unknown environments is a nontrivial investment in preparation, but does help a lot.

Finding suitable issues is way worse; to be tractable they have to be small/easy/low-context and those get fixed very quickly. I usually end up with a document of 'issue ideas' starting a few months before, and write them up on GitHub the week of the sprint. This is a lot more work than just fixing them, obviously, since I'm 'growing low-hanging fruit' on mature projects or starting new projects to suit.

There's no substitute for contributor-focussed docs, ample comments, etc.; but I've found it useful to carve out small chunks of work that don't require contributors to know about the rest of the project - on the level of "fill out this function, the signature and docstring are in the issue". At least for me, mentored sprints are much more about the skills of contributing code to open source projects, not about the skills of programming.

So, some checklist questions for maintainer-mentors:

• How many commands does it take to set up and run your project's tests (etc)? Where are these commands documented?
  (can you get it down to pip install tox; tox?)
• Does this require any tools that a beginner might not have? What happens when the dependencies are missing? Are they cross-platform?
• How much of your library does a new contributor need to know about? Do you have a document explaining your code structure?
• Do you have a complete checklist for new contributors? Fork, clone, branch, test, edit, test, push, pr...
• Can you make a list of really, really easy issues? (and yes, sprint meta-issues are a great way to track these) Target difficulty: add or modify one function, add one test. Our mentees can already code, but have never worked on open source before - let them focus on that!
• Can you list good third issues? Something a little meatier, after two trivial ones to learn the process.