Hey open source maintainers! Empower your contributors with continuous integration
Written by Ricardo N Feliciano.
Surprisingly, many open source projects don’t implement a continuous integration (CI) solution. Perhaps your project is one of these. You might be thinking, “We don’t need it, we know what we’re doing,” or even, “We’re too small, we’ll implement it later.”
When maintainers do use CI, it’s often an insufficient implementation, such as using it for deployment without any testing.
I should know; I’ve been guilty of this myself.
But I want to show you that the decision to implement CI for an open source project is not about you. It’s about providing the right tools for contributions. It’s about enabling your project growing steadily with healthy code.
Using CI in your open source projects will help empower your contributors to make better PRs more easily and help your project grow and thrive.
Read on for four ways that CI can empower your open source contributors:
1. CI will actually run tests
This may seem obvious but it’s quite important to mention. Maintainers that have invested time in thinking about testing for their project need to convey that to potential contributors.
How? You could remind people to run tests:
- In
README.md
- In
CONTRIBUTING.md
- Or in a Pull Request (PR) template
But even with those steps taken, how many people will actually read them and follow through? Running a project’s tests with a CI provider like CircleCI means you don’t have to worry about a contributor being lazy or forgetful. It’s a safety net for the quality of your project’s code.
2. CI build failures are okay; use them as a teaching point
It can be intimidating to contribute to an open source project for the first time. Let contributors know that PRs are welcome, but more importantly, that they don’t need to get it right on the first try. If a PR status check turns red, great! The first thing you can do is make sure users know how to click over to the CI provider and check for the error (the test passing/failing link in the footer of a PR). Don’t assume anything. Then you can give that person advice on how to fix the issue and give them time to do so. The idea here is that this is a teaching point. Remember: they may not knock out bugs at the same pace as you can. The contributor can learn and become stronger while this interaction sets the tone for your project and its community. Be friendly and fix things together.
3. CI allows contributors to work on projects they may otherwise not be able to
I’ll explain this one with a real-world example. Let’s look at the CircleCI CLI, an open source project that is compiled for both macOS and Linux. If a user was to report a bug that specifically affects the macOS build of the CLI I could try and fix it. As an Ubuntu Linux user, I can write the code and even cross-compile, but I can’t actually test it to make sure the fix works. I don’t have macOS.
Enter CircleCI.
I can open a PR with my fix and CircleCI will build and test it on a macOS machine. It has removed a technical barrier for me. Likewise, CI can lower friction for people wanting to open PRs on your project.
4. Don’t require build secrets for non-deployment jobs
When API tokens, SSH keys, etc. are involved in a build, you don’t want those build secrets getting into the wrong hands. This is understandable. Public projects on CircleCI have secrets turned off on forked PRs by default.
We’ve got your back.
What you can do is make an effort to allow forked PRs to reach a green build without those secrets in the first place. Commands that rely on secrets should be isolated to their own jobs or blocked with Bash logic. This way an outside PR will be able to run tests that pass and a project maintainer can come along and run integration tests or deployments in the master
branch or some other way.
Conclusion
An open source project equipped with a CI tool lowers the barrier to entry for contributions while raising the overall quality. Open source is as much about the people as it is the code. Empowered contributors are happier and more productive. This benefits the project which means everyone wins.
P.S. CircleCI gives all users/projects a free build container. Did you know that we give open source projects, specifically, 4 containers? Still for free. Let’s build software together!.
Originally published at circleci.com on December 4, 2018.