I recently had an incredible experience with one of my open source projects that I’d like to share. It’s a story of openness and collaboration that I hope other open source project maintainers will find valuable. This post continues the theme of “building successful open source projects” from my previous article on documentation.

The story

A couple of weeks ago, I released the fourth major version of JSQCoreDataKit. This release contained a number of improvements and breaking changes — a redesigned Core Data stack and a lot of refactoring to bring the library in line with the latest Swift API Guidelines. It was a big step forward for the library and I barely wrote any code for this release. That’s right. Sébastien Duperron (@Liquidsoul) pretty much completed the entire release for me. All I had to do was review and merge his pull requests.

The release was seamless and free of regressions. So, how did we do this?

No regressions

The other kind of documentation

The success of this release was the result of a number of attributes about this project:

  1. It has 100% API documentation
  2. It has 96% test coverage
  3. It has continuous integration with Travis CI
  4. All issues are organized, labeled, and clearly explained
  5. Each release has a corresponding milestone that groups the issues going into it

Collectively, all of these things serve as documentation — not just the API documentation itself. By keeping a project organized in this fashion, you can empower anyone to easily and successfully contribute.

With excellent API documentation and test coverage, contributors can fix bugs and add features without worrying about breaking something. Together, the docs and tests provide the complete picture for how your APIs should behave. Continuous integration keeps this in check by regularly running tests for each change, and notifying you of any regressions in test failures or test coverage. Once travis-ci and codecov.io were green for each pull request, I was certain that it was safe to merge. To me, this is the most liberating feeling in software development.

All tests pass

Transparency via issues and milestones

I work diligently to keep issues labeled and grouped in milestones. I try to explain a task as clearly as possible, so that anyone could read it and know what to do. I open issues for everything — bugs, features, todo items, refactors, future work, random ideas, and anything else. For me, issues serve not only as a way to track work for a project, but to communicate with the open source community about where I want to take a project. I also use issues as reminders for myself, and as forums for discussions or questions.

Milestones allow the community to clearly see the changes made in past, present, and future releases. Using milestones also makes it easier to write a changelog for each release.

With all of the above, the project becomes entirely transparent. The community knows everything that I know. Discussions on design decisions are open source, questions and their answers are open source — nothing is a secret. Everyone has all of the information they need to take an issue to work on and submit a pull request for it, and they can be confident in their changes because of travis-ci and codecov.io. I believe this kind of transparency is the foundation of successful open source projects.

Easier said than done

So that’s what happened. Sébastien was able to synthesize and navigate all of the information and resources on GitHub, and submit a pull request for each issue for the 4.0.0 release of JSQCoreDataKit. We had some discussion and I made few gardening passes to clean up some documentation and formatting, but I mostly sat back and watched. I cannot express how thankful I am for his contributions, and how much time he saved me. The upfront cost of writing tests and docs, and keeping the project extremely organized paid off.

Finally, I must admit that everything I have outlined here is much easier said than done. Keeping documentation and test coverage at or near 100 percent is challenging. Keeping GitHub issues, milestones, and pull requests organized is challenging. It takes time and effort to maintain any open source project, no matter how big or small it might be. But if you do these things then the future of your project will be bright, and the cost of maintaining it will diminish dramatically. You’ll find it easier to merge pull requests and release new versions faster.

Remember, writing the actual code is only half of the work.