Your project’s README is your project’s constitution
Most open source project maintainers treat READMEs as mere marketing material or technical documentation. Yes, your project README can and should tell others what your project does and how they can use it, but at its most fundamental level, the README serves as your project’s foundational document, memorializing and communicating the project’s core goals, philosophies, and underlying assumptions.
Well-focused projects are healthy projects. Among the first things I do when I start a new project is to write a one- or two-line description of what problem(s) I intend the project to solve (the project’s goals) as the first line of the README (immediately after the project name). For complex projects, maybe it grows to a few bullets. One of my favorite examples of this is the choosealicense.com goals. As you continue to write new features, refactor old ones, and gain contributors, those goals will sit there unchanged, and often slip into the back of your mind. And that’s just fine.
It begins with a well intentioned pull request
About six months will go by while your project (hopefully) gains popularity. One day, a well intentioned user will submit a pull request to expand the project beyond its original scope, trying to solve a problem you have no personal interest in solving, a solution that will be difficult for you to maintain, or one that complicates solving the problems you really care about solving. At this point you have two options:
- You engage the contributor on the merits of the pull request they painstakingly hand crafted (“is this a valid problem to be solving?”), or
- You engage the contributor on whether the problem they’re trying to solve furthers one of the project’s goals (“is this part of the problem we’re trying to solve?”).
Option 1 almost always ends in a choice between scope creep and hurt feelings, because they wouldn’t have submitted the pull request unless it was a problem they were personally facing.
Defer to the README
With option 2, you link back to the README, explain that you don’t believe the pull request will advance the project’s purpose, and suggest that if the contributor thinks the project’s goals should be revised or expanded, that it’s a valid suggestion, but that the appropriate forum to do so is in a pull request updating the README, where the entire community of contributors — not just those interested in this particular feature — could have a dedicated and in-depth conversation about the project’s raison d’être. As we wrote in opensource.guide:
If people are overly focused on debating the merit of a particular feature, it may help to revisit your README and talk about the higher vision of your project. Focusing on your README also depersonalizes the conversation, so you can have a constructive discussion.
Pull requests should solve exactly one problem
This approach mirrors the common technical mantra, that each pull request should solve exactly one problem. If a pull request review is forced to answer two questions (1) “is this the right technical solution to the problem?*, and (2) “are we solving the right problem?”, the “right” way to do it is in two distinct pull requests to keep unrelated discussions distinct and adequately memorialized.
To continue the legal metaphor, deferring to the README is the open source equivalent of appealing to the Supreme Court. Just as the US Constitution sets the foundation for what the US government should and shouldn’t do and how it should go about solving problems, so too does a project’s README dictate the four corners of the project’s efforts and the means by which it’s permitted to solve them. Think of it as a contract between the project and its users saying “this project will provide the service of tackling these problems in this way”.
Moving beyond bullets
As your project evolves and becomes more mature, so too should your stated goals. Maybe you expand those goals to document the project’s philosophy, like WordPress and Jekyll do. Maybe you add an explicit code of conduct. You might also need to document any underlying assumptions you’re making about the problem space. Eventually these may move to dedicated docs, but almost without exception, they begin their legal existence as a line or two in the README (and not solely in your head or communicated ad hoc).
When you start a new open source project, you know what problems you’re trying to solve and how you’d solve them. As the project matures, “you” becomes “we”, and it becomes even more important that you write down these foundational beliefs so that you can communicate them to others and establish shared norms (which you can then later enforce without prejudice or drama). Your project README doesn’t just communicate the “what” and “how”, it communicates the “why”, and serves as your most effective tool to combat open source scope creep and technical debt.
If you enjoyed this post, you might also enjoy:
- Twelve tips for growing communities around your open source project
- Five best practices in open source: external engagement
- Why open source
- Everything an open source maintainer might need to know about open source licensing
- 15 rules for communicating at GitHub
- Why you probably shouldn't add a CLA to your open source project
- 19 reasons why technologists don't want to work at your government agency
- Ten ways to make a product great
- Eight things I wish I knew my first week at GitHub
- Four characteristics of modern collaboration tools
- The seven things a corporate Chief of Staff does
Ben Balter is the Director of Engineering Operations and Culture at GitHub, the world’s largest software development platform. Previously, as Chief of Staff for Security, he managed the office of the Chief Security Officer, improving overall business effectiveness of the Security organization through portfolio management, strategy, planning, culture, and values. As a Staff Technical Program manager for Enterprise and Compliance, Ben managed GitHub’s on-premises and SaaS enterprise offerings, and as the Senior Product Manager overseeing the platform’s Trust and Safety efforts, Ben shipped more than 500 features in support of community management, privacy, compliance, content moderation, product security, platform health, and open source workflows to ensure the GitHub community and platform remained safe, secure, and welcoming for all software developers. Before joining GitHub’s Product team, Ben served as GitHub’s Government Evangelist, leading the efforts to encourage more than 2,000 government organizations across 75 countries to adopt open source philosophies for code, data, and policy development. More about the author →
This page is open source. Please help improve it.
Edit