Puzzle Driven Development + Hacktoberfest = Contributor-friendly project

#hacktoberfest #opensource

Puzzle Driven Development, an Agile methodology invented by Yegor Bugayenko, is a way to break down a large task into smaller tasks using TODO comments (called “puzzles”) and an automation tool that converts them into GitHub issues where people can discuss and take on these work items.

The generated issues are automatically closed when the originating TODO comment is removed from the source code.

When working on each TODO item, you have 1 hour to complete the task (some teams prefer 30 minutes). You do what you can, and the rest you put in more TODO comments as subtasks. (See the original PDD article for an example.)

I’ve used this methodology with great success in the ELECT Live project, an open-source website that shows the live score during 2019 Thai general election vote-counting. It is part of the ELECT initiative. The general election was near and they were looking for contributors, so I volunteered to help out as a front-end architect in that project and decided to try out PDD.

As it turns out, PDD enables us, within 8 days before the general election happens, to work on the project and communicate what needs to be done without the usual overhead of having to track the status of issues manually, to attract tens of contributors, and to close hundreds of issues.

But why did it work so well?

Divide and conquer.

It lets you break down big tasks into smaller tasks as you go, as needed

Instead of the lengthy process of breaking down tasks upfront (sprint planning anyone?), I quickly created a simple skeleton with a bunch of placeholders.

Now, the webpage has been broken down into multiple sections. Each section has a placeholder content with a TODO marker. One big task has been broken down into multiple smaller puzzles.

Smaller tasks means your project becomes more contributor friendly

Instead of having to spend hours implementing a component according to the specification, we gradually evolve the component towards what we want. The part where we didn't finish, other people can help.

In the image above, you can see a placeholder box turn into a placeholder component, into a working (but ugly) component, and into a more beautiful component. In fact, at least 5 different people worked on this. Some contributors are totally new to the project.

It also allowed me to better focus on the more important things most of the time.

For example, most web developers know how to style a webpage. But only a few people know the architecture of the entire project. It would not be as efficient if these key people had to spend a big chunk of their time adjusting CSS to be pixel perfect.

So, at one point I wanted to focus on data-binding and getting the contents to render. I decided to work on just that part, and leave the aesthetics part as puzzles to be solved later. While I switched to work on another component, other developers jumped in and help improved the aesthetics. More jumped in and improved the UX. And so on.

PDD tools

Few tools are available to choose:

0pdd, the original hosted tool: http://www.0pdd.com

For ease of setup, I highly recommend this tool.
todo-actions (by me): https://github.com/dtinth/todo-actions

This one integrates with GitHub Actions and requires a MongoDB database. You’re in control of your data but setup is more complicated.
(know any other tool? please comment!)

And it’s Hacktoberfest!

Having learned about the effectiveness of PDD, I decided to try it on my side project, Bemuse, a web-based open-source rhythm action game.

This project started in 2015 when async functions were not standardized yet. At that time, generators and promises are becoming the ES2015 standard, and so we used the co library to convert a generator into async functions.

Fast-forward to 2019, now we have async function built into Node.js and web browsers. So, it’s about time to convert the remaining usage of co to async functions!

But instead of creating a big and rather tedious issue of having to convert the whole codebase, I grepped for 'co', sprinkled TODO comments into the source code, and let a bot turn them into issues: