In my mind, the best and safest way to invite contributions into an open source project — and therefore, a good system for project maintainers to use — is the fork and pull method. To understand why that’s the case, let’s review what a fork is, what a pull request is and the four things that any project can add to make it easier to drive engagement between maintainers and contributors.
Forking is the name we give to a workflow that uses the tools we have available to develop software and commit changes back to a project. For anyone new to open source, I’ll run over the basics of that process below. If you already know how it works, skip down to the *.
To make a change in an open source project, first go to the project repository (at GitHub or Gitlab, perhaps) and click the “fork” button. That copies the project’s repository to your account. This forked project is now yours to change. Your changes create a “fork” in the software’s development that will head off in its own direction (hence the name) until the changes get folded back into the project. The kind of forks I’m talking about here, by the way, are always ones where you fully intend to contribute your changes upstream back into the project.
Once you have your own copy of the repository, you can explore the project in your own sandbox environment. You can learn as much as you want about it, understand how code is tested and built within it and then try fixing issues yourself. If you are new to the project, a great way to get familiar with it is to run the test suites included or build it yourself.
The work you do here will be the foundation for any changes that you propose back to the project in the future and the way that you propose those changes is to use the pull request. In an open source project, anyone can contribute a pull request back to the upstream repository.
When you make a pull request, you are starting a dialog with the maintainers about changes to the code base that you believe will add value to the code base. These changes could be a new feature, a bug fix or an enhancement to the project tooling used to build and test the code base.
The resulting contribution is then reviewed, reworked if necessary and finally approved by the project maintainers. When everyone’s happy, the changes get merged into the upstream master/main development branch. Changes are often merged first into a topic branch that is used to stage big changes and that can be incrementally developed before getting merged into the mainline development branch for the project.
*The great thing about the fork and pull workflow is that it is cyclical. Once you are done with a particular code review, you can go back and find another issue to deal with (sometimes referred to as “cutting a branch”) and keep working. A contributor can even have multiple pull requests going through the development -> code review -> development cycle at the same time.
That’s not the whole story, though. From my experience working on the Angular components in the Clarity Design System, maintainers can add four things to a project that make it easier for anyone new to a project to get involved and contribute. These are:
- A Code of Conduct– this is a basic set of behavioral norms that everyone working on the project is asked to follow. These norms help ensure that people are treated with respect, that their time isn’t wasted and that they aren’t discriminated against. As a result, they help remove what would otherwise be barriers to them contributing.
- Contribution Guidelines– these detail the process for how changes should be proposed, developed and added into the code base. They help clarify and streamline the contribution process.
- Coding Guidelines– these detail any specific conventions (e.g. file structures, folder names, file names) that the project uses and help contributors avoid wasting their time on code that doesn’t meet project specifications.
- Automated Consistency– this uses automation to help new contributors meet a project’s standards. It might automatically check that new code is properly linted (checked for security flaws), for example, and suggest any fixes required. Similarly, it can ensure that code is formatted to the project’s house style. The open source tool Prettier does this nicely.
Looking at this from a maintainer’s perspective, you might ask whether it’s really worth adding all this overhead just to make things easier for newcomers? The first thing to say is that making things easier for novice contributors is a huge deal. You want to go out of your way to do that. But the fork and pull method, when supported with these four additions, benefits the project itself no matter who is contributing.
In particular, it confers three big advantages:
- Security– this is especially important for a project like Clarity where the code is used in many products across VMware. With open source, you can’t verify who your contributors are or know their motivations for sure. Given that, you need to understand exactly what people are putting into your project. Done right, the fork and pull workflow ensures that all changes are properly reviewed before they are accepted, no matter who they came from.
- Standardization– the fork and pull process lets you incrementally improve your entire code base over time as you make changes to your coding guidelines. As you upgrade parts of your library or add new features, you can make sure they conform to those standards.
- Iteration– the iterative nature of the process lets you continually refine and improve the changes that are being made. The fork and pull workflow model gives you multiple points at which you can iterate and improve upon any changes before they become finalized.
Advantages like these are why fork and pull is the gold standard—not just for allowing new contributors to make an impactful contribution from the start but for maintainers, too.
In my next post, I want to look at the process some more from the maintainer’s perspective and offer a deeper dive into code review. What’s the secret to making code review comprehensive, efficient and – above all – high quality? Stay tuned to the Open Source Blog for when that piece goes live later this week.
