What it took to onboard the first contributors.
On Saturday, September 5, VolunteerPress stopped being a one-developer project. That was the day of the first contributor onboarding session, held at Improving in Columbus during the Christians in Tech Columbus meetup. The first contributors got their laptops out and started setting up their development environments. The session itself is easy to describe. What's worth writing about is the set of decisions that made it possible, and what watching contributors use them changed.
VolunteerPress is a WordPress plugin, so to work on it you need WordPress running on your own machine, which means PHP and a MySQL database. To check the code the way the project checks it, you also need Composer and Node. That's five things that have to exist and agree with each other before you can change a single line of code, on whatever laptop you walked in with. The goal was concrete: someone should go from nothing installed to passing the same automated checks the project runs before every change, in one sitting. Every decision below came from that.
That goal decided the foundation. I chose LocalWP, a free desktop app that runs WordPress sites on your computer and ships its own PHP and MySQL. Docker is the more standard answer, and it's what the WordPress core team uses for its own contributors. LocalWP won for three reasons. Onboarding is faster, because PHP, MySQL, and WordPress arrive together instead of one install at a time. The environment is standardized, because every contributor runs the PHP and MySQL that LocalWP ships, whatever their operating system. And it has a site shell: one click opens a terminal with that site's PHP, database, and WordPress command line already wired up, so everyone starts from an identical place on Windows, macOS, or Linux. It's also a tool WordPress developers already know from client work, and it works well for contributors at every skill level.
The trade-off is that contributors depend on a desktop app instead of assembling standard tools themselves, and if LocalWP changes something, our setup guide changes with it. For this project, that's worth it.
That choice shaped the setup guide. It has three sections, one per operating system. Windows, macOS, and Linux each get their own path to installing LocalWP, Composer, and Node, and those three installs are the last point where the operating system matters. On Windows, for example, Composer needs to know where PHP lives, so rather than have people install a second copy, the guide points it at the one LocalWP already downloaded. From the moment you open the site shell, every command in the guide is identical for everyone. I wanted a contributor on Windows and a contributor on a Mac sitting next to each other to be able to look at each other's screens and see the same thing.
Then there was deciding what "done" means for setup. Loading the site in a browser isn't it. Passing the checks is. Every change to VolunteerPress, including a one-line fix to a documentation file, has to clear four of them: the PHP coding standards check, the JavaScript lint, the JavaScript unit tests, and the PHP test suite. Right now that's 620 PHP tests with 3,720 assertions, and 21 JavaScript tests. The PHP test suite needs a live database and a setup the project only supports on Linux, so the work is split. Everyone runs the first three checks on their own machine, and GitHub runs all four automatically on every proposed change, whatever machine it came from. A contributor on Windows or a Mac never has to get the PHP test suite working locally.
Running checks for a typo fix sounds excessive, and I understand why. The reason to do it anyway is that the first time a contributor runs those commands, they're not really testing the code. They're testing their environment. If the checks pass, you're set up, and that's the point where the setup guide hands you off to picking up an issue.
The other decisions were about access and process. Contributors now join a Contributors team in the GitHub organization with triage permission on both repositories, the plugin and the volunteerpress.org site. Every change starts as a filed issue, so there's a record of what's being worked on and why before any code moves. The one exception is an emergency fix, a security issue or a live-site outage, which can go out immediately as long as the issue is filed the same day. The record stays complete either way.
I also rewrote the issues labeled good first issue. A title and a sentence isn't enough for a first issue. Each one now names the files involved and says what "done" looks like, so a new contributor can pick one up and know when to stop.
One more rule is about how the code gets written. Last week I said Claude Code wrote the code for version one while I owned the architecture, the requirements, and the testing. That's still how it works, and contributors are welcome to work the same way. The rules that matter now live in the contributing guide and a conventions file, where both a person and an AI coding tool can read them: the four checks, the issues-first workflow, and review before anything merges. There's a small file at the root of the repository that points any of those tools at both documents, whichever one a contributor prefers. An AI-assisted contribution goes through the same four checks and the same review as any other, and the contributor owns the result.
Very little of the work to open the project up was code. At launch, the plugin already had its tests, its coding standards, and a clean architecture. What it was missing was everything a second developer needs before touching any of that: a way to get a working environment, a definition of when setup is finished, a definition of when an issue is finished, and the project's rules written down somewhere other than my head. Opening VolunteerPress to contributors meant building those things.
The setup guide that went into that session was a first version, not a final one. Every question a contributor asked that afternoon pointed at an assumption the guide was making without saying so. The steps were all there. What they needed was the clarity that comes from people willing to sit down, try it, and say where it stopped making sense. Those questions produced the version in the repository now, and that's how every part of VolunteerPress moves: it ships, people use it, and it gets better. That's what building in the open, with other people, gives you.
So here's the change since last week. VolunteerPress is a team now, and it meets in person. For now, onboarding happens at Christians in Tech Columbus meetups. If you're in Columbus or anywhere nearby and you'd like to build something that nonprofits will actually use, come to one, bring a laptop, and tell me you want in. You don't need to be a WordPress developer, and you don't need to be a regular. Where onboarding happens will change as the group grows beyond the meetup. Online sessions for people who can't make it in person are part of the plan, with no date yet. Any changes will be posted at volunteerpress.org/contribute. If you'd rather ask a question first, write to hello@volunteerpress.org.
