A year or so ago I wrote the In Person Event Handbook to help people prepare their projects for in-person events like workshops, hackathons, and sprints. With the PyCon 2015 sprints coming up, I thought I’d take a moment to write up the highlights. Want to make your project welcoming to newcomers? Read on!

Step 1: Articulate Your Goals & Expectations

Why are you participating in the sprint? What are you hoping to accomplish over the next few days? Are you hoping to expand your community? What are you happy to teach newcomers, and what would you prefer they already know?

One of the most useful things you can do is to think and talk about what your expectations are. For instance, if you only want newcomers who are proficient in python, that’s totally okay – but it’s important to say explicitly, so that beginning programs can find a sprinting project (like OpenHatch) where we’re happy to teach basic skills.

Knowing what you want to accomplish can help you pick tasks for newcomers to work on. One mistake I see people make is to say, “You can work on anything you want! We’re happy for any help.” That’s a great impulse, but it can be overwhelming for newcomers to choose from a wide variety of options. Follow up with: “That said, here are our highest priorities for the sprint. Would you like to work on this specific task?” (See more about picking specific tasks in Step 3.)

Step 2: Check Your Set Up Process

One of the biggest time-sucks at events – and in open source development, generally – is getting the development environment set up. It’s a chronic problem in large part because it’s really hard for maintainers to fix by themselves. They’ve already got the dependencies installed and the projects running on their systems. Unfortunately, it can take newcomers hours or even days to accomplish the same, especially if they’re developing on a different operating system than the one the maintainers are.

One way to tackle this problem is to recruit some newcomers and have them go through your setup process while you’re available in real time, via IRC, video chat, or in person. They should work from the already existing documentation. When they get stuck, you can help them identify the problem, and either you or they can file documentation and proccess issues in your tracker to be fixed before the upcoming event.

We call this a “setup sprint”. If you’re interested in doing one, let us know, and we’ll help you find newcomers to work with. Another option is to go through this process as the first activity at the event. It’s up to you!

Step 3: Gather Some Tasks Ahead of Time

It’s important to have a pre-selected list of tasks for newcomers to work on, rather than letting them loose on your issue tracker. When drawing up your list, we recommend the following:

• Include a variety of tasks, not just coding tasks. Consider adding documentation, design, publicity, and/or community management tasks. You may also have meta-tasks: for instance, you might like to have someone go through your issue tracker and flag issues that need to be reproduced. Or you might like to have someone reproduce some reported issues! These tasks can be difficult to capture in the issue tracker itself, so we encourage you to have a document elsewhere, for instance on a wiki or etherpad, that covers any tasks not on your issue tracker.
• For coding tasks, try to find tasks which are self-contained and don’t require intimate knowledge of your codebase. Where possible, add information to the issue about which files, functions, etc would be involved in the fix, so newcomers know where to start.
• Other information to add to issues includes:
  – Clear explanations of what the current and desired behavior is. How will the contributor know that they’ve successfully addressed the issue?
  – What skills or tools will be involved in fixing it. This will help contributors decide if it’s a good issue for them to tackle.
  – Other changes they may need to make. Will they need to update the test suite? The documentation?

Some of this is information you might just tell newcomers at the event, but if you address it ahead of time you free yourself up to focus on more in depth mentorship, or to work on more issues yourself.

OpenHatch will be running an introductory workshop at 5:30pm on 4/12, which is the Sunday night before the PyCon Sprints.  Please join us as either an attendee or a mentor!

Have additional questions or advice? We’d love to hear about them.

See you at PyCon!