Making Your First Pull Request

When I started teaching myself to code, the majority of it was in isolation. I would read books, watch videos and do interactive tutorials online. Then comes sleep, waking up and doing the cycle again. I was learning a lot, but I felt like I was missing something. I was missing the enjoyment of working with others, building real things used by people. The validation that I could implement the things I was learning.

I started doing Open Source work in my free time in May 2015, almost by accident. After a series of contributions I joined Hoodie as a collaborator. With Hoodie, I started looking into making the project more accessible for new and experienced developers alike. In turn, this led me to wonder how we could make all Open Source projects adhere better to the word 'Open'.

Project Collections

There are many websites that list Open Source projects on GitHub that have issues for beginners:

Sadly when I look at the issues listed I found a lot of the same things

  • Issue had no real explanation of the problem, or solution

  • The project hadn't been updated or maintained in some time

  • The issue had already been solved and just hadn't been closed.

  • Everyone has widely different ideas of what is 'easy', and it often isn't.

There are many reasons why this happens. Being a maintainer is hard and stressful. Sometimes things slip through the net and you can't keep up with all the chores you have. The bigger the project, the harder it can get.

Though, I was still left frustration. I'm willing to give my time to projects who need help, but it felt like no-one was telling me how I could!

Your First PR

So I created Your First PR. I spent 8 hours on the first day rifling through all the open issues on GitHub with labels like 'easy', 'starter' and 'beginner'. I started tweeting ones that I thought were suitable for new programmers and Open Source beginners.

List of tweets on the Your First PR Twitter account

A few days later it had over a thousand followers and people were starting to make their first ever pull requests. That was in September 2015. Now, it's close to 4000 followers and has helped over a hundred people make their first pull request.

What makes a good issue?

So, what makes a good issue? Let's take a look at this one, aimed at someone new to accessibility and the Hoodie website project.

Hoodie Accessibility GitHub Issue

Title: [Accessibility] Give the Hoodie Logo meaningful alternative text

It has a title that clearly indicates what is needed. You can scan all the open issues and find something either within your skill set, or is something you're interested in learning.

Labels: bug, help wanted, starter

It makes good use of labels, with 'bug' indicating that it is something that needs to be fixed rather than a new feature implementation. 'help wanted' vocalises that we do actually want someone to submit a pull request for this. 'starter' is the tag we use at Hoodie to show that this is a good first issue for a new contributor. Try to pick one label for this, and avoid using the word 'easy': it never is.

I then provide a detailed list of instructions. describing how to pick up the issue and get started, then link to every code line that needs to be altered to include alternative text. I also write how the issue fixer can reach out to me, should they get stuck.

Why bother?

That issue took about 15 minutes to write. The fix itself would have taken me 5. So, why bother?

Well, I've fixed this kind of issue many times and have written many alternative texts for images. I also know how to work with the repository for the Hoodie website. The biggest gain for me fixing is that we make the website a little more accessible, which is awesome.

But, what if someone new to programming or open source fixed it? They may learn: how to work with GitHub, the basics of accessibility and how to work with the Hoodie project. They make their first foray into Open Source and perhaps they contribute more to Hoodie or find other projects to contribute to. If they're like me whenever I submit a pull request, they gain confidence in themselves.

Although the first way is faster, the second way is invaluable and much more is gained by both parties.

How can you help?

If you encounter a bug within a project that you know how to fix, write an issue instead of fixing it yourself. Clearly explain the issue so that someone who has never worked with your project can understand it. If you know the solution, write steps on how to do that.

State in your project README what label is used for beginner issues, providing a link to them in the issue tracker.

Then, send that issue to me! I'd love to share as many welcoming issues as possible, where we can help people to make their first pull request.

What's the plan for the future?

I don't have any. A bunch of nice people have talked about growing Your First PR and they have some fantastic ideas. But, I'm quite happy to exist just as a little twitter account that shares great issues and cool emoji.

I want to help people to write good issues, and I want to help people make their first pull request!

Would you like me to give this blog post as a talk? Check out my talk proposal!