So, You’d Like to Start an Open Source Project

Regular readers of this blog are no strangers to free and open source software. From Firefox to Brave, Node.js to OpenSSL, and jQuery to React (finally), today’s web developer can’t get very far at all without relying on “FOSS.” However, there is a huge difference between consuming FOSS and maintaining FOSS. The latter task is not as well understood, although such an understanding is critical for the success of any project.

In this post, we’d like to share the considerations we make before introducing a new project. Make no mistake: it’s a lot of work. From selecting a license to following open governance and promoting developer ergonomics, you’re signing up for all sorts of responsibilities that you could skip if you kept your code to yourself (or your team). In case the social benefit of FOSS isn’t enough for you (or your boss), we’ll explain how the practice pays dividends in project health. This isn’t a guide for creating a famous project–there’s too much luck involved for that. Instead, you’ll find our thoughts on doing well while doing good in software development.

Licensing

There are a multitude of licenses that qualify as both free software and open source software. The Free Software Foundation maintains a list of the former, and the Open Source Initiative maintains a list of the latter. Numerous resources exist online to help differentiate between the alternatives (here’s one from the GNU project and here’s one from GitHub.com), though for folks working in collaboration with a legal team, it’s probably best to let them suss out the details.

At a high level, the most important distinction concerns “copyleft.” Licenses like the GNU General Public License require that derivative works be released using the same license. Compare this to “permissive” licenses like the MIT “Expat” which allow others to re-package the code in non-free/non-open-source projects. Unlike the finer legal distinctions, the decision here is highly subjective and may require some soul searching.

Beyond that, avoid writing your own, and avoid adding additional constraints.

Process

Technically speaking, software qualifies as “open source” from the moment it is published with an appropriate license. In a more practical sense, however, that event is only the beginning. Software is not a static resource; it evolves over time. Maintainers are expected to facilitate this process transparently and inclusively.

Governance

While the owners of a FOSS project have the final say in its direction, they also have a responsibility to engage with their user base in a way that is fair and consistent.

Orientation This includes responding to contributions (whether bug reports, feature requests, or source code submissions) in a timely and professional manner. The process is informally known as “triage,” and depending on the size of the project and its user base, it can require a significant investment of time and energy.

Whatever version control system is in use, projects benefit from following a well-defined branching model. This allows potential collaborators to discern where work is occurring and participate as appropriate.

Release management Project owners should schedule new releases of their software with a cadence that is amenable to general consumption. This means regularly making new bug fixes available and delaying the publication of incompatible changes. The latter type of change inevitably produces extra work for consumers since they have to carefully alter their own code in order to upgrade. Following a “conscientious” release cycle reduces the frequency of these interruptions. It also avoids fragmentation of the user base, meaning that there are fewer versions in active use. The net effect is that more people receive the latest bug fixes.

Fostering inclusivity One of the reasons individuals begin to contribute to a FOSS project is to learn and grow. They may expect to accrue rights and responsibilities in proportion to the significance of their work. The project owners must be willing and able to invite these individuals into leadership positions. Note that this may be more difficult for those projects that are stewarded by a private organization, so this consideration is important to resolve prior to releasing the software.

Policy documentation Effective governance should be well-documented. All the project management considerations which may be internalized by a small co-located team should be published in text alongside the source code itself. This includes (at a minimum): a technical roadmap, contribution guidelines, and a code of conduct.

Maintenance Considerations

The decision to maintain a project as FOSS informs even the technical workflow.

Versioning When releasing new versions of their code, maintainers should clearly label releases with meaningful version numbers. The appropriate convention depends on the context of the software (e.g. programming language, package repository, etc.), but for JavaScript projects (particularly those published to npm), this usually means Semantic Versioning. Whatever the case, maintainers are expected to understand and consistently follow their chosen versioning scheme.

Technical documentation Excellent open source projects include comprehensive technical documentation. The canonical index for this documentation is a file named README located in the root of the project.

Developer-facing projects (libraries, SDKs, etc.) should describe their programming interface in detail. These descriptions give consumers the confidence they need to rely on the interface from their own code. Such low-level descriptions are necessary but not sufficient because they do not help developers discover the project’s capabilities or any idiomatic usage patterns. For that, the project should also provide usage examples in the form of sample source code.

Whether the project is intended to be included in software or deployed as an application, it should provide demonstrations of typical behavior. The nature of the project will inform the fidelity of the simulation. For instance, a user interface component can be demonstrated in a much more realistic way than a programming language binding for an HTTP API. In any case, though, such “demos” help orient potential users to the project and decide between available alternatives.

Maintainers should also keep a release history which summaries the bug fixes, new features, and known incompatibilities of every release. Typically located in a file named CHANGELOG or HISTORY, this information is critical to supporting users across multiple releases. It serves as a reference for those looking to upgrade to new versions, explaining the benefits and risks they should expect.

Automated tests As much as possible, project maintainers should encode their expectations in a machine-verifiable form. This includes not only expectations for correct functionality (what the software does) but also for preferred process (e.g. source code/commit message formatting–what the contributors do). Automation promotes efficiency in the contribution process because it focuses technical review on novel details. Rigorous documentation can provide similar benefits, but such documentation also increases maintenance overhead and friction for new contributors.

Promotion

All of the preparation described to this point would be meaningless if no one was aware that the project existed. Promotion is yet another responsibility of the project leadership–at least until awareness reaches a critical mass within the target audience.

First and foremost: the source code has to be made publicly available. This may seem self-evident, but it involves the subjective decision of web hosting provider. Project owners should expect to make trade-offs between cost, platform openness, and the expectations of their audience. (Increasingly for many types of projects, the service of choice is GitHub.com.)

Maintainers should also distribute their projects via one or more “package manager” repositories. The appropriate repository is context-specific. For applications, it depends on the target operating system (e.g. “dpkg” for Debian/Ubuntu or “HomeBrew” for macOS). For software libraries, it depends on the programming language (e.g. “PyPI” for Python projects or “CPAN” for Perl projects). As noted in the introduction of this essay, far more people rely on FOSS than contribute to FOSS, so package distribution is in some ways more critical than source code distribution (though it is by no means a substitute).

The release of the software should be celebrated with an announcement on the audience’s preferred communication channels. This may include technical blog websites, IRC chat rooms, mailing lists, microblogging services, or any other social media.

Benefits

By maintaining code as FOSS, project owners open the door to improvements from third parties. These contributions come in the form of bug reports, new feature proposals, bug fixes, and even feature implementations. The volume and quality of these contributions cannot be taken for granted, however. They depend on the good stewardship of the maintainers, the relevance of the software, and luck.

These benefits may seem paltry when weighed against the expectations and responsibilities described in the previous sections. However, that work is not simply a means to attract free labor. With the exception of “promotion,” every responsibility described above enhances the experience of contributing to the project, improves the quality of the source code, and increases the chances for success. Even if the source code was never used outside of a maintenance team, the practices of strong FOSS projects would still bring great value to the team.

Finally, we can’t overstate the altruistic value of free and open source software. The freedom to run, copy, distribute, study, change, and improve software are critical to ensuring users are in control of their system and its output. We recommend the philosophy of the GNU project for readers unfamiliar with this perspective. While these practices have the potential for social good, they’re just one aspect of the way great technical projects make a positive impact on the world. Following SemVer isn’t going to make up for privacy violations, and not even the best code of conduct will put a dent in the tech industry’s diversity problems. If you’re looking to do good, then don’t forget that FOSS is not an end but rather a means towards a higher purpose.