How to win friends and open-source your software

by Floor Drees

Or: How to make your project open source ready

Did you open-source a piece of software and wish you weren’t the only soul slaving away at it? Then this article is for you. We are putting in an effort making a Phusion legacy project (Ruby binaries ‘container’ Traveling Ruby) pull request-ready and wanted to share our steps with you.

1. Add community standard files

GitHub helps you tick all the boxes on the community standards checklist, recommending adding ‘community health files’ such as README, CODE_OF_CONDUCT, LICENSE, or CONTRIBUTING, in the root of your repository. You can add these documents directly from Insights > Community.

For a how & why regarding the Code of Conduct, as well as templates, GitHub comes to your rescue. GitHub user Purplebooth published a great README template. For licensing and contributing files there are a myriad of examples to choose from as well.

As dry as it might be, your repository’s license will aid communicating expectations, managing contributions, and protect everyone’s legal rights (including your own).

In your README, try to answer the following questions:

  • What does this project do?
  • Why is this project useful?
  • How do I get started?
  • Where can I get more help, if I need it?

A CONTRIBUTING file articulates how to participate in your project (and signals that this is a welcoming project to contribute to). Include information on:

  • How to file a bug report and suggest a new feature (for Traveling Ruby we use issue and pull request templates)
  • How to set up your environment and run tests
  • The types of contributions you’re looking for
  • How contributors should (not) get in touch with you

Bonus points:

  • If your project is not yet ready for production, write this information down in a disclaimer in your README!
  • If time allows, try adding additional documentation, such as tutorials.
  • Link to a community platform outside of GitHub (like Slack) if that's where you want the conversations to take place.

2. Consider your language

Newcomers to your project will turn to your issue tracker and look at (merged) pull requests, discussion forums, mailing lists or chat channels to form an idea of what your project is like and how and where they can best contribute. Optimizing these channels for onboarding contributors will set you up for success.

If you’re at the beginning stages of open sourcing your project: pick a name that is easy to remember, gives some idea of what the project does and is NOT offensive or plain silly. Puns might not translate well and some of your potential users might be company employees that have to explain referencing your project in their libraries.

What makes your project different or interesting? Why did you create it? Answering these questions for yourself will help you communicate your project’s significance. Using inclusive language (such as “them”, even when referring to the single person) can go a long way in making your project feel welcoming to new contributors. Also: stick to simple language, as many may not be native English speakers.

Optimize for code readability by code commenting (albeit not best practice), adding tests and avoiding one-liners. Your coding style will set the precedent for future code contributions.

3. Stay on top of your issue tracker

Frequently engage in code triaging, comment on and close duplicates, reference issues and pull requests and label issues ‘beginner-friendly’ or ‘design’ / ‘docs’ if you’re looking for contributions other than code.

Issue threads quickly derail with discussions only slightly related to the original problem. It’s your job if anyone’s to steer the discussion back to sanity lane. With every comment, ask yourself, “(How) does this bring us closer to a resolution?” If the conversation is really starting to unravel, try and refocus. The most productive attempts to end comment wars have one thing in common: suggesting a solution / approach and asking for buy-in. Taking ownership like that is not for everyone but, as a maintainer or core contributor, does lay out the larger vision for the project and shows you’re all about solutions, not 'busy-keeping'.

There’s also the outcome of some study that says contributors who received code reviews within 48 hours had a much higher rate of return and repeat contribution.

4. Marketing your project 101

You can’t just open source and expect people to join (not even with all the community files in all the right places). Instead, consider creating a website for your project. A website makes your project friendlier and easier to navigate, where documentation and tutorials might get lost in your root directory. If your project is hosted on GitHub, you can use GitHub Pages to create a website fairly quick.

Take advantage of existing online communities and platforms to reach your audience. Fat chance that you’ll find your audience on Stack Overflow, Reddit or Hacker News. Find these channels, search for people experiencing the problem that your project solves, answer their question, and when appropriate suggest your project as a solution.

Being an active member in the open source community will help you develop relationships and good will for your project. Don’t expect free labor if you’re not willing to do the work yourself.

5. Ask for feedback

Ask people who go through the process of creating a pull request about their experience. It’s a shame there’s no way of knowing who dropped out before hitting the pull request button and why, but at least try and gather some feedback from the people who made it to the finish line. Where was your documentation lacking? Where did they get their information from? How did they make decisions? How and why did they decide to work on your project in the first place? What issues did they run into?

Open source offers the unique ability to learn and improve your coding as well as people skills. Still on the fence whether or not you want to publish your project for others to play with? Consider whether you can afford the time commitment it will probably require to maintain an open source project. Start paying close attention to how other maintainers support their communities and consider they also started with just one tiny piece of software and a README.

Do you have an open source project you’d like to share and receive contributions for? Please share those with us on Twitter (@phusion_nl)!

We are excited to support the Ruby open source conference format ROSS conf Amsterdam, May 11-12, with the Exercism, RVM, Homebrew and Traveling Ruby projects represented.