(Written by Asheesh and Britta)

On Saturday January 4, eight OpenHatch volunteers, new and experienced, gathered in San Francisco to work together on improving the OpenHatch website. We took over a couple tables in a cafe with a sprawl of laptops, cords, huge salads, and people asking each other lots of questions.

To prepare for the event, Asheesh Laroia and Susan Tan followed the In-Person Event Handbook, a guide maintained by Shauna Gordon-McKeon. Susan sent pre-event announcements and acquired a generous food sponsorship from the Python Software Foundation. Asheesh worked on a list of tasks people might work on, and after the sprint ended, updated the list of tasks with their current status.

Out of nine sprinters (Susan, Ni, Nate, Meghan, Mark, Jack (remote), Britta, Becka, Asheesh), four were new or almost-new contributors to OpenHatch — exciting! Thanks to Susan for reaching out to the Hackbright community to help invite new contributors.

More about the structure

New contributors sometimes find themselves lost while trying to find some part of the project where they can make a difference. As part of pre-sprint prep, per the Defining tasks for attendees recommendations, we identified the following categories of useful things to do:

• Reviewing pull requests that fix existing issues, and giving people feedback, or merging them
• Fix technical issues that are obstacles for new contributors
• Read documentation for clarity, and fix if possible
• Fix high-priority technical issues that are obstacles for users

Within each section, we mentioned specific tasks, including:

• A plain-English description of what to do
• An estimate of how long it might take
• Where to find more information, such as a bug report link
• The skills and tools needed to achieve the task
• Who, if anyone, in the room was working on it

You can see a snapshot of that document taken when the event ended.

To help attendees know what to expect, we sent an email to the OpenHatch development mailing list before the event began.

We think that spending time coming up with these categories, and naming specific tasks, helped people understand how they could best use their skills and interests. The plain-English descriptions helped people find something to work on. One person who cares passionately about Python web app deployment found a Heroku-related issue to address; another who loves copy-editing found a way to do that. Yet another person who had her own ideas got to work on them, successfully ignoring the list!

Most of all, since the list was already prepared when attendees arrived, we could focus our mentorship time on answering questions about how to do something, going beyond just what to do.

What we worked on

• Meghan, a brand-new contributor to OpenHatch (and to open source projects!), tackled a mysterious and strange bug that had been lingering in the bug tracker for a long time: when searching the volunteer opportunity finder, and using voice input (such as on Android), the placeholder text in the search field wasn’t cleared properly. Neither she nor anyone else could reproduce the issue, so she simplified the implementation to use the HTML5 placeholder attribute rather than possibly error-prone Javascript. It’s always a great pleasure when new contributors’ first commits are a net removal of lines of code! Working on this in person supported lots of interactive question-answering, resulting in a stellar, well-tested pull request that was quickly merged.
• Ni Mu, who had previously contributed to the design of The In-Person Event Handbook but hadn’t contributed much to Python projects before, evaluated a reported bug with the training mission teaching using diff and patch, and closed it as already resolved. Yay for clearing out bug tracker cruft!
• Nate Aune, a new contributor to OpenHatch, improved documentation of how OpenHatch uses Heroku, and improved code to make the app’s migrations run properly on PostgreSQL, which is the database engine on Heroku. Asheesh merged these changes and added some commits on top to fix small formatting issues.
• Becka (who first joined us at the 2013 PyCon sprints) read through pull requests, including this very pleasant one, and she learned more about setting up a local environment for working on OpenHatch.
• Britta Gustafson, who has been a communications volunteer for a few months, wrote down suggestions for homepage improvements (Let’s link important things from the homepage and Let’s also put more social media on the homepage), and she made initial mockups and then discussed them with other contributors. It was pleasantly effective to have an in-person focused conversation about significant visual changes instead of just sharing screenshots via IRC and email. After the sprint, we iterated more on the mockups and Susan implemented the changes, and they are live. Britta also fixed some broken styling that was hiding text in a useful old blog post.
• Susan Tan, who has been contributing to OpenHatch code for a few months, began the significant task of deleting a feature that hadn’t really worked well for a while — a map on the people search page — which is now successfully removed from the site. She also answered questions for new contributors. Additionally, before the event, she had sent announcement emails and worked with the Python Software Foundation to get food sponsorship.
• Mark Holmquist (who was a first-time committer at an in-person sprint in May 2012) reviewed pull requests that fixed CSS and wording problems, and he reviewed the text on the Open Source Comes to Campus website, suggesting edits to improve clarity and consistency. These improvements are live.
• Jack Grigg, a long-time contributor, reviewed some code-removal work first submitted at the Grace Hopper Conference Open Source Day; he revised the commits, and Asheesh pushed them. In the past, we used celery for background tasks; we’ve simplified our codebase to not use celery at all, and this removes all traces of celery from the app.
• Asheesh, who had the most experience with the codebase, had prepared the list of tasks for new contributors to work on, and worked with attendees to answer questions or review code.
• Post-sprint, John Morrissey (a long-time contributor who first joined us at PyCon sprints) asked on the email list for more guidelines on how to review code contributions with small issues. In response, Asheesh created an ASCII flow chart.

Thanks and follow-up

A couple things we forgot to prepare, to remind ourselves for next time: a specific plan to take a photo of everyone (our photo is missing a couple people!) and bringing name tags. After the sprint, we walked over to a nearby bar for beer and non-beer, and we chatted some more. (Interestingly, we sent out a post-sprint survey but most participants didn’t fill it out; the events mailing list later had a good discussion of how to get post-event feedback.)

If this sort of thing sounds like fun to you, join the Devel mailing list and stay tuned for the next sprint announcement!

Thanks to Susan Tan and Asheesh Laroia for all their pre- and post-sprint organizing work. Thanks too to all the attendees, in-person and remote.

We’re grateful to the Python Software Foundation for sponsoring food!

If you’re interested in running an event like this for your open source project, check out the Python Sprints website to learn more about food sponsorship, read the In-Person Event Handbook, and join the OpenHatch outreach event community to ask questions!

Bonus for those who scrolled this far

Please enjoy our new patch-review flow chart.


+--------------------------------------------------+
| Is the submitter sitting right in front of you? |
| (A presence in online chat, e.g. IRC, counts.)|
+--------------------------------------------------+
+ +++
yes | no
+ | +
| | +
| | |
v | |
+-------------------------------------+ | |
| Ask them to revise the submission, | | |
| after providing detailed review, | | |
| and make sure to help them resubmit | | |
| in case they have questions. | | |
+-----------+-------------------------+ | |
| | |
| | |
+-----------v-----------------------+ | |
| Did they finish revising the | | |
| submission to your satisfaction | | |
| before they left your presence? | | |
| | | |
+-----------------------------------+ | |
+ + | |
yes no | |
+ + | |
| +-----------------+ |
| |
v |
+-----------------------------+ |
| Merge it (and say thanks!) | |
+-----------------------------+ |
|
+-------+
+-----------------------v------------------------+
| Do you have a reasonable belief that |
| they will respond to feedback within a |
| short period (e.g., 2-3 days, tops)? You |
| might look at their responsiveness to past |
| comments to get a sense of that, and/or their |
| general tone on the pull request, e.g. their |
| degree of tiredness/frustratedness vs their |
| degree of eagerness. |
+------+-----------------------------------------+
+ +
yes no
+ +
v +--v------------------------------+
+--------------------------------------+ | Are they an experienced |
| Leave a comment indicating the | | contributor, whose last commits |
| code style issues you have, | | indicate that their concept of |
| preferably pointing to existing | | code style is similar to yours? |
| OpenHatch docs or mailing list | | (For first-timers, choose "no".)|
| posts about the style, and say that | +---------------------------------+
| you hope they'll get a chance to | + +
| make the desired changes, but even | yes no
| if not, you'll be happy to make them | + +
| yourself and merge it on or after |+-----v---------------+ |
| 3 days from now. Leave a note saying || Do like this, but | |
| if they want more than 3, just ask. || "a month" instead of| |
+--------------------------------------+| 3 days. | |
^ | | |
| +-----+---------------+ |
| | v
| | +----------------------------------------+
| | | Thank them for this |
| | | contribution, and leave |
+-----------------------------+ | a detailed review indicating |
| what changes you would make |
| and that you have pushed their |
| work, with those changes on top. |
+----------------------------------------+