At thoughtbot NYC we’ve been running first-time open source contributor workshops, Ruby-focused. We have met a lot of people getting into the tech community, who have heard a lot about open source but don’t know where to start. We have aimed to create a safe space where people can contribute to real projects with peers and mentors around to help them make their first pull requests. We have run the workshop six times, and each time we ran it, we improved it a little bit. This is what we have learned.
Before the event
Before the day of the event, we make sure we:
- Announce the event a month in advance. In our case, we do it through the Hacker Hours meetup group, a four-thousand-people community of people who “come with their laptops, sit and hang out and code, and flag down one of the organizers if they have a question”
- Have the office space available with enough hot and cold beverages, fruit, snacks, power outlets, internet, enough chairs, six tables for groups of five, name tags and sharpies
- Have about one mentor per project
- Announce guidelines before the event:
- ask people to set up their development environment beforehand if possible. This will maximize the time that people are able to spend focusing on the project.
- send instructions for entering the building and office
- stress the time the event starts and finishes
- Have a concrete list of projects (and issues within the projects) to work on. We typically pick 18F, thoughtbot, and Exercism.io projects. It helps to pick projects that are easy to set up, and ideally that mentors are familiar with.
Other suggestions:
- If you maintain open source projects, keep good issues tagged and open for
people to tackle as their first contribution (using
help wantedorfirst-timers-only) - Using a spare computer, server, or virtual machine, run the development setup steps beforehand. Incomplete and confusing setup instructions are consistently the biggest challenge for new contributors in these workshops, which is discouraging.
Setup is a challenge. It takes time and is not encouraging work. Enforced Ruby
versions in .ruby-version or Gemfile in the projects, Nokogiri as a
dependency, old PostgreSQL installations, can each take a portion of the day for
newcomers. Ideas to mitigate this:
- Ask attendees to setup as much as they can beforehand
- Create installation scripts
- Pick projects with fewer dependencies (no Nokogiri or other gems with C extensions!)
- Begin the workshop with a “setup” section or working group
During the event
At first, we thought we’d provide a long list of project options for participants to choose from. But, setup time aside, it took more than an hour to select a project, and then a particular issue within the project, to only then start reading the relevant documentation, the code, learn the necessary git spells, etc. In our experience, people were more interested in learning the process of contributing than in where they were contributing to. Starting used to feel slow, but now we pick one project per table, introduce them, and have people go to the table they are interested in, meaning the event gets started quicker.
It’s good to put up banners near each table defining projects for each group, so people working on the same project are close enough to help each other.
We say a few words before we start:
- We explain what each project is about so that people know how exactly their work will help others
- We describe what the collaboration process looks like for maintainers and contributors. We tell them that sometimes project maintainers won’t respond, in which case it’s good to gently nudge them
- We make it explicit that opening up new issues, asking questions, or sending suggestions are valuable contributions. People sometimes think that submitting code is the only way of contributing, but there are many ways to make a project run smoother which don’t necessarily imply code changes
We found that 4 hours with a break in the middle is a perfect time. It allows people to build up context and start doing work, get confused a couple of times or more, get a bit tired, have a fun break were to get to know peers, and then continue to work with a fresh state of mind. Ideally, they end the day with at least one contribution. If we don’t call for a break people will stare at screens for four hours straight, and that’s not our idea of fun.
Charging a nominal $3 was useful to keep RSVPs accurate. Otherwise, people forget they RSVP and only two-thirds end up coming, which can be problematic when trying to fill up a space comfortably or calculating how much pizza, snacks or beverages to prepare. The nominal fee kept sign ups coming in at a slower pace than for the free meetups we run but didn’t prevent us from filling the space and having a wait-list. Also, it’s a low enough price point that it didn’t filter out people who are at the beginning of their careers, which is an audience we want to work with.
Some people need hands-on mentors. As a mentor, it’s best to avoid touching their keyboard, so they learn by themselves. Having one mentor per about five attendees works well for us. Encouraging attendees to work together pairing, or help each other, or just present themselves with one another makes the help of mentors less necessary, while attendees teach and learn from one another. Having Open Source maintainers and mentors available in Slack and GitHub is helpful, so feedback comes in real time.
We typically get many first-time contributions, and people are visibly excited about that. On the way, people learn a lot. I once paired with a newcomer to release a new version of a gem, set up his SSH public and private keys, learned to “fork” a repository, and to send a Pull Request along the way.
In NYC? Come to our next workshop!
If you are around New York City, you should come to our next event, so we get to work together and chat in person.
Do you run similar events? What works well and what doesn’t for your group? Let us know on twitter.
