Get involved in open source today!

Lessons we learned building the Apollo Client project

A little over a year ago, we at Meteor Development Group were looking for a way to build the data layer of the future. GraphQL ended up grabbing our attention mainly because it offered a solution to the problem we were trying to solve at the time: how to let clients use just one intuitive query language to query many different backends — Postgres, MySQL, MongoDB, etc. Completely flouting the principle of “not-invented-here”, we decided to see if we could use GraphQL instead of building our own solution in-house.

GraphQL checked all the boxes, except for one: there was no easy-to-use client library. There was Relay, but Relay had a notoriously steep learning curve, only worked with React, and didn’t integrate with anything else, not even React-Router. We tried to bend Relay to our will and make it easier and more flexible to use, but quickly realized that it was an almost impossible task because of how tightly coupled Relay was.

A community-driven GraphQL Client

We were convinced that for GraphQL to be widely adopted, it had to integrate with other popular tools in the Javascript ecosystem, and we believed that the best way to achieve that goal was to involve the open-source community from the start. In short: we needed to build the GraphQL client “for the community, by the community”.

At Apollo we strongly believe in the power of open source, but as many of you know, building open source software can be both a source of joy as well as frustration. In this blog post I want to share a few lessons that we’ve learned, in the hope that this will encourage and enable more people to start successful open source projects, because:

Every time an open source project succeeds, we all win!

1. Getting off the ground

The biggest hurdle for every open-source project is to get the first user and the first contributor. It’s usually only when projects become really successful that contributions start pouring in. Unfortunately, there’s no easy shortcut to getting there; you have to make the first step and build something to get the project off the ground.

However, if you’re working on something exciting, you can almost always find someone who has the same problem and who’d be happy to start contributing if you take the lead (a friend, a coworker, a lost soul somewhere on a forum)!

That’s exactly how things worked out with Apollo Client: Sashko Stubailo started writing code and quickly found James Baxley III as our first contributor and production user. James was a core contributor from the beginning, and he still maintains react-apollo to this day. Thank you James!!

2. Getting the word out

Successful open source projects — those that help the greatest number of people — are just as much about getting the word out there as they are about quality code. For a project to succeed, it needs to have both. Every once in a while a project comes along that’s so great that word gets around without the authors lifting a finger. That generally only happens to one project out of a thousand, so you’ll have to get the ball rolling yourself.

I really can’t emphasize enough how important it is to start getting the word out there so new users and contributors can find your project. An open source project stays alive only as long as it has users who are also able to contribute to it. There are probably hundreds of amazing open source projects that disappear because no one found out about how great they are.

For Apollo Client, this very publication is the main way we reach new users and contributors. We simply set ourselves a goal of writing two posts per week, even if there wasn’t anything specific to write about. If there were no news to share about the project itself, we simply wrote up some of the insights that we had while working on the project, like how to do pagination or a comparison between GraphQL and Falcor.

You don’t need to be famous to start a blog on Medium, all you have to do is sign up and start writing. Literally anyone can start a blog, or post on Reddit, and submit stuff to Hacker News. Do it now!

If you’re thinking about waiting on that blog until the code looks nicer, until the documentation is better etc., here’s a secret tip: don’t! Your project will never be perfect. In fact, if you’re like me, you’ll never think that your project is good enough. Fortunately, it doesn’t have to be. The sooner you talk about it the better: nobody expects a project or idea to be perfect in the early stages, but if you wait until you think it’s perfect, it will be difficult to make use of helpful criticism.

There’s another upside to writing and talking about your project early: We’re usually not the best at judging the merit of our own projects. If you put your idea out there early you can get feedback much sooner, and focus on building what’s really valuable. You might even find some early contributors that way.

3. Making it easy to understand

As I mentioned earlier, an open source project lives and dies by its contributors. Apart from getting the word out early and often, a critical part of acquiring new contributors is to lower the barrier of entry and make it as easy as possible to contribute. If you can explain your project’s purpose to someone in a few sentences and get an example running for them in a few minutes, the chances are much higher that they’ll be able to understand enough about your project to be able to contribute to it.

Here are a few ways that we used to make Apollo Client easier to understand:

• We have a demo that anyone can run, or copy-paste from
• We have extensive documentation
• We wrote blog posts about many of the concepts and features
• We made Apollo integrate with Redux because everyone gets Redux.

There’s still room to do a lot more, which is why we’re constantly working on improving our documentation and creating better examples.

4. Empowering contributors

Maintaining an open source project requires constant effort. Responding to issues and fixing bugs can be a lot of work, especially if your project becomes successful. It’s much better if that responsibility can be shared by more people. The best way to do that is to empower contributors and make sure they get the appreciation they deserve. Your goal should be to enable every contributor to become a potential maintainer.

Empowering contributors is one of the best things you can do for your project, because it will not only greatly increase the amount of work that can go into the project, it will also make the project much more likely to survive if one of the core contributors/maintainers pulls out.

Here are some of the things you can do to empower contributors:

• Respond to issues and pull requests as soon as possible (but don’t overwork yourself)
• Give people an opportunity to fix the bugs they find. Make sure to give them all the instructions they need to succeed.
• Work with contributors to get their PRs merged quickly. As a new contributor, it’s very motivating to see your PR getting attention from the maintainers.
• Make your project easier to contribute to by enforcing good coding style and good tests.
• Let contributors make major contributions and listen to them when making major design decisions.

On Apollo we’ve been incredibly lucky with the contributors we’ve had. Each of them contributed their own expertise to our project, and without them we wouldn’t be where we are today. Thanks to James Baxley III we had an invaluable early production user of Apollo Client. Nick Nance helped us refactor graphql-server and now maintains and uses its hapi integration. Hagai Cohen took it upon himself to do a complete rewrite of graphql-tools in Typescript and has contributed major features to graphql-server as well. Thanks a lot guys, you are awesome!!

Of course that’s only the tip of the iceberg, and we have many more great contributors that I wish I had the space to write about here! Each and every contribution makes a difference, no matter how small. If you’re one of the contributors, thank you very much for your efforts! I hope I’ll get a chance to write about your help in a future post!

Conclusion

While getting off the ground and getting the word out are things that should require less and less of your time as your project matures, making your project easy to understand and empowering contributors are things that require constant attention. These are also the things we still feel like we need to improve on the most:

• We still need to make the project easier to contribute to by simplifying the code and writing better documentation.
• We still need to get better at empowering and connecting with contributors.
• We still need to work harder to get PRs merged and issues resolved quickly.

Despite all the things that still need to improve, I’m extremely optimistic and constantly amazed by how far we have come: In less than 10 months Apollo Client went from zero to over 1600 stars on GitHub. It now has 60 contributors and over 2300 commits in 86 releases, and with over 10,000 downloads per week it is the most popular GraphQL client on npm!

None of this would have been possible without our amazing community of open-source contributors, so a big Thank You to all of you!

Join the open source community!

Alright, after all this talking, it’s time to take action! You too can become an open source contributor or maintainer!

To build to Open Source software!

If you have an idea for an open source project, write up your idea and then share it with the rest of the community! If you feel the itch to start coding right away, that’s okay too, but remember to get the word out.

If you want to contribute to open source software, are interested in GraphQL, or simply like learning new things, consider joining the Apollo community! We’re a welcoming bunch, and there’s always plenty to do.

Go to our GitHub repos and find a project you’re interested in, or sign up for our Slack and join the contributing channel.

Let’s move Open Source forward together!