Issues With First Timer Issues

I’ve noticed more open source software projects creating “first timer issues”. Written up in more detail than usual these issues explain a known, easy-to-solve problem reserved for first time contributors to that project. At their most extreme they spell out everything down to the commands and exact text changes required to make a contribution.

This post highlights problems I have with this approach. Note I’m intentionally not linking to any other posts or projects because any project doing this has shown admirable empathy for new contributors and I want to add to a wider discussion and not grumpily wag my finger at anyone.

Why even open source software?

Let’s take a step back: what is open source software for? I’d say every project is seeking to solve a problem in such a way that near-identical wheels are not endlessly reinvented by every individual that needs a round, rolly thing. In short: people get together and build something useful: great! With this in mind: why do we want people to contribute to open source? I’d suggest there are two angles:

  1. more open source software contributions help open source software get better over time
  2. more open source software contributors learn more about and get better at software development (or at least open source software development) over time

We contribute to make open source better

Good, high-quality contributions to open source projects make the project more useful for everyone. They take load from maintainers self-imposed obligations and in doing so make the software better for the end-users. Over time, more end-users means more contributors and more maintainers: good news for everyone. However, first timer issues don’t achieve this virtuous cycle. Intentionally leaving defects in projects to help someone contribute is putting the cart before the horse; you’re choosing to make the software worse to get more contributors.

If every “first timer” ended up being a maintainer and fixing hundreds of issues this would be a worthy pay off but this is not the reality of open source development. When you discourage regular, enthusiastic contributors from fixing bugs then users, contributors and even maintainers frustrated by these defects will move on to other projects.

Contributing to open source makes us better

I’m not of the school of thought that open source code contributions somehow automatically make you better at software engineering or are some benchmark of success in the technology industry. I have, do and will continue to work with engineers who are vastly better at their job than I will ever be and who don’t have a single open source contribution to their name. That said, for me open source development has been and continues to be a great learning experience and hobby and I’d love to see more people benefit as I have.

If I was directed to “first timer issues” when I was getting started out in open source I would have learned far slower than I did. Software development is not something you can learn by following someone else’s instructions to completion. You learn by taking higher-level tasks, breaking them down and iterating. You learn and grow often through the frustration and confusion of not knowing how to do something. If you are trying to teach someone golf you don’t start by holding a ball above a hole for them but trying to teach them to hit a ball they will miss more often than hit to begin with. Similarly, figuring out how to solve a problem is a more important skill than making the actual fix.

Well, what do we do instead?

If not “first timer issues” then what should projects do to attract first time contributors to open source? Start by getting back to the fundamentals: an open source project exists to build useful, high quality software. If you’re maintaining one of these projects primarily in your spare time: it should be fun and not a chore. Don’t allow yourself to be guilt-tripped into doing anything you don’t want to be doing and doesn’t benefit you in any way. Maintainers having fun attract more contributors who want to have fun.

Automating contributor workflows, documenting your processes and creating tooling to reduce friction for new contributors is fun for me and it can help attract new contributors. If it’s not fun for you: don’t do it! If fixing a bug is too frustrating: don’t do it! Your open source license’s legalese will literally say you make no guarantees your project even works and have no responsibility for any issues that arise when it doesn’t. Issues that you want someone to fix but you don’t want to are good “help wanted” issues; soliciting the contributions that you don’t want to make (and I told you not to).

If you want to get started in open source and don’t know how don’t go looking for an arbitrary project you don’t use with issues written up telling you how to solve them. Consider the open source software you use already and write open source code to make it work better for you. If this ends up used by no-one except you: who cares. It’s still useful to you and you’ll have learned something creating it. This can mean you don’t contribute overnight to a project run by others or when you do your first contribution attempt doesn’t get accepted but that’s all fine. The goal is to have fun, learn something and solve problems instead of ticking a “contributed to an open source project” box.