On Running an Electron Contributor Training

Electron, despite its popularity with application developers and its 80,000 stars on GitHub, needs more contributors. The list of things that could be better is long; the number of people able and willing to work on them limited. If you work in Open Source, that's probably familiar to you.

To turn aspiring contributors into real ones, we maintainers organized a "Contributor Training": A two-day workshop teaching engineers the art of building and improving Electron itself. This post summarizes what I've learned.

Motivation: Why a workshop?

Before you can dive into the project's code, you first need to build it from source. Electron contains parts of Chromium, all of Node.js, and a bunch of cross-platform C++. Considering dependencies, we're talking about roughly 60 millions lines of code. Downloading that takes hours, building it the better part of a day.

Having onboarded interns and new team members at our various employers, we also know that getting a build environment setup is harder to do without a mentor. We have guides and documentation, it's possible – but it's certainly easier with the wisdom and reassuring words from someone who walked the same path.

Our goal for the workshop was to bring engineers who wanted to make the jump from using Electron to maintaining it – and guide them the same way we would onboard a new colleague. Furthermore, it's been a while since someone joined the project without being mentored through the first couple of days, so we wanted a fresh new look on where exactly our documentation and tools fall short.

Logistics: Getting the show on the road

You need a space, catering, and a curriculum. Then, said space needs to be filled with participants and teachers. The requirements are identical with developer workshops I've ran in the past.

Space We're grateful that Microsoft let us use their community space, the Microsoft Reactor in San Francisco. Having had a sponsor on the inside helped, but their program is generally open to the engineering community and available in multiple cities.

Catering We had breakfast and lunch on two days as well as various snacks, which came out to $2,227 for the roughly thirty people present. We ended up ordering from local restaurants and used Instacart for the snack order.

Participants We decided to combine the training with Covalence Conference, the closest thing we have to an official Electron conference. We advertised the training on the conference's website and via Twitter. We limited ourselves to 20 participants and decided to sell tickets via Electron's OpenCollective, a straightforward tool to collect funds as an open source project. The price for a ticket was an extremely modest $150 – a steal by any means – but we didn't quite know how many people would be interested.

Turns out that we could have ran the workshop twice – and had to turn many people away. Companies betting on Electron find value in having someone in-house who understands how the platform actually works.

Curriculum Electron is maintained with a fairly complex governance model, which includes an "Outreach" working group. We came up with a basic curriculum in a fairly short meeting, gave each bullet point an allotted amount of time, and assigned directly responsible individuals to each time slot. Planning a whole workshop is a lot of work, while creating a two-hour session on tips and tricks about debugging native crashes is a lot more doable.

Teachers Other maintainers saw value in a training and made the time to come by. Not everyone needs to get up in front of the class and speak for an hour, merely having existing maintainers in the room to support participants during coding is already tremendously valuable.

Mistakes: Things I've learned

1. I vastly underestimated our participants. As mentioned above, setting up electron/electron is a laborious task. We made some last-minute improvements to our build tooling leading up to the workshop, so participants got instructions about how to setup their environment only with a week's notice. If half the class arrived with all dependencies in place, I would have been happy – but instead, only two people did not already successfully build on their local machine. Both individuals encountered tricky-to-debug errors that nobody reasonable would have expected them to know how to fix.
2. I did not leave enough flexibility in the schedule. I expected that we'd spend at least two hours just getting everyone's environment setup. Since that wasn't the case, we were off schedule the second people told me they're good to go. What's more, some of our participants turned out to be vastly faster learners than others – and I didn't have sufficient "stretch goals" for them to work on. Having a stretch goal for each interactive task makes planning a lot more difficult, but I fully expect that it would have paid off.
3. I did not prepare enough real-world issues to work on. Given how much people surprised us with their proficiency, we started working on real issues by the end of the first day. Finding an issue that can be reasonably brought to a satisfying conclusion in a few hours isn't easy – and I should have done a better job by preparing a few of those.
4. We did not get everyone to submit a PR. We knew from the get-go that having your first PR merged into something massive is addictive. As we all know, not every valuable PR needs to be a 5,000-line refactor, there are seemingly infinite opportunities for small project improvements. I absolutely failed to make sure that everyone submitted at least one PR. Out of all the mistakes I've made, this is my biggest regret.

To put a bow on this post: I had tons of fun, and I hope that both my fellow Electron maintainers and participants had an equally good time. I'd love to do it again. I also can't wait to see how sticky this training was - and whether or not it'll actually yield more contributors working on Electron.

Special thanks to Electron's outreach working group and all the wonderful maintainers sharing their time and knowledge.