This is a book about the social interactions and situations that are the underpinnings of the open source world. It's about how humans collaboratively create software.
This isn't a programming handbook or a guide to using GitHub. If that's what you're interested in, there are links in the bibliography to great resources.
Specifically this is about creating open source software. Open source software, loosely defined, is software that is free to share. Typically, open source software is released under a license that reverse-engineers copyright in order to protect this right to share, instead of doing copyright's traditional work of restricting sharing.
The ramifications of this tweak to copyright are tremendous. Open source software doesn't have to be a closely-guarded secret: instead, it's usually created in public spaces, shared widely, and distributed for free. Since everyone can read the source code and contribute changes back, software projects can become collaborative projects between multiple companies, private individuals, foundations, and even governments, all sharing in the work of creating software and the benefit of having it.
The successes of open source software have been world-changing: the Linux operating system runs the majority of the Internet, the git version control system is the basis for GitHub, and thousands of other pieces of open source software make everyday life possible. On a personal level, open source software and the systems of collaboration it comes with have enabled people to work remotely, make friends, and learn about parts of systems that were previously the exclusive domain of experts.
But that's the ideal. The everyday work of creating things is difficult and fraught - filled with the same social difficulties as any other job, along with unusual new challenges. How do communities scale when they contain differing opinions and styles? How do decisions get made without formal power structures - or does decision-making require the creation of such structures? What about the way that these projects interact with companies who wield the power of commerce, users who have the power of speech, and developers who may have more technical skill than collaborative ability?
The world of technology is filled with fascinating technical challenges and big esteem boosts for whoever can factor primes faster or reduce latency. But people problems are the ones that decide whether most projects succeed or fail. Software projects are made of people with priorities, feelings, and needs. The daily tasks of a project maintainer often have nothing to do with typing C++ and lots to do with resolving conflict and balancing concerns.
That's what this short book is about. We'll discuss some common situations and the tricks you can use to handle them, as well as larger problems that have no clear answer. Thinking hard about non-technical problems has made me a better participant in open source, and I hope these ideas can help you as well.
Hi, I'm Tom. I've worked on tens of open source projects over the span of over ten years. Some projects have taken off, acquired a life of their own. Others have failed. Some have produced software with thousands of users and lots of contributors, others have produced software with hundreds of thousands of users and almost nobody writing code.
This short book is taken from my experiences in this field, research, and observations of many projects and communities coming and going throughout the years.
Programming has a persistent focus on the craft: the craft of writing code, of programming and understanding technology and techniques. The skill of writing and reading software is hard to acquire and is the shorthand differentiator between 'technical' and 'non-technical' people in the field.
But the experience of producing software quickly reframes the picture. Technically brilliant people can't survive alone. People who can build communities command as much influence as those with supernatural coding skills.
This shouldn't be a surprise coming from any other industry, where building networks and relationships is a recognized part of the business. But in software and especially in open source software, so-called "people skills" are underemphasized and perhaps more complex than other fields.
I think it's necessary to say a few words about cultural context, because it matters. The social situations we're going to discuss are all relative to who you are, where you are, and who you interact with. I can observe other people's lives, but I have only one, and that is the life of someone who is generally on the top of the bell curve of the technology-industry demographic: an American white man in his late 20s.
This is relevant. Emotional labor is a useful concept for understanding this area of life: in certain job roles, there are expectations about another person's emotions and tone. In America, baristas are usually expected to be bright and cheerful. Bartenders should be friendly and familiar. And these expectations are typically gendered: outwardly showing that you're having a bad day when you're a woman is different than when you're a man.
Some of the patterns that I recommend for being friendlier and more understanding of other people's needs and feelings may be old news to you if you have needed to adopt that tone already. Or they may be a big adjustment if your identity doesn't require you to be especially kind or bubbly.
I don't want to fill this text with buzzwords, but a few are necessary to say what I want in this limited space.
If you use software, you'll encounter bugs. Sometimes software does the wrong thing, or doesn't anticipate what you want to do with it.
With open source software, it's easy to write to the software developers who write applications and libraries. But communication is an art, more than ever. A good bug report includes the right information, in the right place, and with the right tone. Here are some tips for how to write a bug report that will make both you and a software developer happy.
This bug report for GitLab.org is perfect: it gives specific steps to reproduce the issue and says exactly what behavior was expected and what behavior occurred. In this guide, we'll walk step by step, through the things you need to say in a bug report.
Software developers are people too.
Maybe the bug ate your homework, or it's taken you hours to track down the culprit and the bug is something really silly, something that nobody would ever do. It's okay to be personally annoyed, but don't take your anger out on another person: nobody deserves abuse.
Many open source projects have adopted a Code of Conduct to make their norms, rules, and responsibilities explicit. If a project uses a code of conduct, review it first before drafting your first message.
And while a bug may be critical or preventing you from finishing a project, it's not useful or appropriate to insist a developer prioritize it. They may have other issues that are far more important, whether professional or personal. If an issue is truly urgent, you may want to hire someone to fix it, or try to fix it yourself.
Sometimes software works in one place, for one person, but doesn't somewhere else. Your operating system, browser, and other installed software all has some impact on the bugs that crop up.
Include basic information about your setup to make issues easier to debug. If it's a web-based application, include:
For installed software and libraries, there are some other things to report:
a package manager, or from source
If it's a web application, you can be extra nice by opening up your browser debugging tools, seeing if there's an error in the Console, and reporting it exactly, by copying & pasting the text.
If you find a bug in a library, like a jQuery plugin or kind of module you use in your own software, try to provide a minimal example or test case that demonstrates the bug.
You can create a GitHub Gist to share a longer code snippet, or if your bug is best demonstrated with live HTML, JavaScript, and CSS, services like JSFiddle and codepen make it possible to create an example that actually runs on the web.
The key to creating examples is making them as small and focused as possible. Isolate the bug's behavior from any other code and technology in your application so that it's immediately clear what the issue is and maintainers can quickly run the example.
It's broken...
When you report a bug, it's because something is wrong. Writing simply that software is 'broken' or 'crashes' doesn't give a software developer enough information to fix it. A great bug report specifically says what you tried to do, what you expected, and what the software did instead.
I added 2 + 2 in my calculator.
I expected it to give me a result of 4.
Instead, it gives 5.
"It Crashes" is not a good bug report: it's like telling a doctor "it hurts" without specifying how, when, or where.
Crashes have many distinct varieties that you can distinguish by using more and better words. For instance, "the browser tab crashes with a sad face icon" or "the browser tab becomes unresponsive" or "my computer crashes". Descriptions like these, that replace the ambiguous "it" and use a more specific word than "crashes", help get issues fixed.
If the project has a bug tracker, like GitHub issues, JIRA, or Phabricator, report the bug there, and there alone. Developers will be notified and respond.
If you aren't sure that what you're seeing is a bug, don't ask whether something should be working or should be broken - just report it in full, and the developer will follow up with clarifications.
Search the bug tracker first for the issue you're going to report. Active projects will often have a long discussion already started about exactly the issue you're running into.
When you find an issue, the first thing you should do is to click the subscribe button. This will subscribe you to the thread, triggering email updates when someone posts back to it. Never post +1, 'Any progress?' or other sorts of pressuring comments to threads.
Why is reporting a bug so hard that it justifies so many words?
Software is fragile.
Your Honda Civic might run for a hundred miles with the oil light on. A piece of tape will keep your headphone table working even when it starts to fray. Humans relentlessly keep living despite sickness.
Software is fragile. Forgetting to type a single character breaks an entire system.
Software has multiple levels of fragility. The applications you use are released under some corporation's name - Apple, Adobe, Microsoft - but are built on the work of thousands of others. They inherit bugs from the languages they're written in. They can inherit bugs from the operating system you use. Or bugs in other systems that they talk to, like servers or other devices.
So reporting bugs is hard because there are so many potential causes for any specific bug. Many bugs are only triggered after a specific series of actions, some of which might be mistakes on the part of the user.
Regardless of the cause, the fundamental problem with most bug reporting is a lack of clear communication.
The next section, about maintaining software, presumes that you have software to maintain and users to respond to. In other words, it assumes you have a project with some degree of success.
Let's discuss success.
You probably have a few definitions about success from the rest of your life. Success might be making connections, helping others, learning, self-expression, earning respect, or something else entirely. In the context of software, your goals will probably be pretty similar. Our driving reasons are usually deep-seated and take a long time to change.
If you look at a site like GitHub, it is gamified in
some obvious ways:
be adapting your software into something new.
are discussing a project.
Gamifying something means that you simplify it, just like any representation will simplify the actual experience. It isn't GitHub's fault that they can't capture success in a number: nobody can.
These gamified elements might line up with the things that make you feel happy and accomplished, or they might not. Don't mold yourself to fit them. There are lots of important and impactful projects that don't fit the gamified criteria: projects that have influenced shifts in technology but don't attract much attention, projects that have more social and interpersonal benefit than they have downloads on GitHub or npm.
We won't cover luck.
Building great software usually requires experience: there's a big gap between academically or theoretically good ideas and things that work in reality. In other words, it's unlikely you'll hit a home run on your first try.
There are two ways to get experience: contributing to other people's projects and rewriting your own. You should do some of both. Established projects have learned some lessons, tend to have processes in place, and when they've made mistakes, have explained and started to understand how they happened.
Rewriting your own projects is also important. Just like drafting English, your best work is often in the second or third draft. And until your projects have lots of users, the disruption caused by gigantic shifts is negligible.
Popularizing open source projects is very similar to advertising and selling a project. Some open source projects even have logos and websites that are higher-quality than the closed-source or SaaS alternative.
But don't overthink communicating or 'branding' your project, the most important thing, the one thing that you cannot do without, that so many people mess up is simply a sentence that clearly describes what it is and what it does. Getting that written gets you most of the way there.
Usually someone will include 'keep it simple' on the list of factors for success. I don't think this is a very useful framing of the issue: rarely do people, even novices, aim for complexity. Instead, they tend to overcommit on what the project should be and what it should do, and the extra complexity is necessary to fit the expanded idea.
Keeping your idea for the project small enough to accomplish is key: this is scoping, and it's often something that a product manager will do. If you don't have a product manager, and even if you do, scoping is part of your job as a programmer. Detect and deflect additions to the scope that will make your project too complex for you to maintain and perfect.
Open source projects with ground rules tend to be more successful than those that operate ad-hoc. Rules are mutually-understood principles that are usually set in English or code. Examples of rules include:
In the case of automated tests and code style checks,
turning your preferences into automated rules saves you time. Poorly-written or incorrect code doesn't require a detailed code-review - instead, you can point to the explanatory errors given by the test suite or style checker.
You need to moderate the community that forms around your open source project, and having a Code of Conduct gives you consistency and predictability: by reading the CoC, a member of the community will be able to know what kind of behavior is appropriate, and what the consequences of inappropriate behavior are.
Over the past 10 years, open source licenses have become very liberal. New licenses like the BSD license permit a lot of different uses and adaptations: if you use this kind of license, a company can integrate it into their software
and sell that software, or redistribute a modified version of it. But licenses have limits: usually they require some form of credit. And even this minimal requirement is often ignored or knowingly broken, and in these cases, choosing a specific license gives you legal recourse.
If you don't know which license or code of conduct to use, here are two good defaults:
A contributing file is an overview guide for how to contribute to an open source project. If you're using GitHub, creating a file called CONTRIBUTING.md will cause that file to appear at the top of the issue tracker whenever anyone starts to create an issue.
Nadia Eghbal's Contributing Template is an excellent place to start for creating a CONTRIBUTING.md file.
If you're using GitHub to run your project, you're likely also using their issue tracker - a simple system for people to report bugs or request features. Compared to most issue trackers, GitHub's issue tracker is freeform: an issue is anything with a title and a free-text body.
Luckily, GitHub introduced issue templates: files that you can include in your repository to pre-fill issues for people. This lets you add lists and other kinds of required structure to encourage people to follow useful patterns.
Open Source Templates is a crazy but super useful "choose your own adventure" style website that provides a range of different issue templates geared to different kinds of open source projects.
Before you create that new repository, write the tweet, or start googling for the best new functional programming framework, take a moment to reflect.
You're probably building this software because you want to. You want to build it because you have a need, something that doesn't exist in the world, or just an itch to scratch so that you can learn something new.
The worst case is that you waste your time and end up with a new responsibility. You might only have a few users, but even their costs will add up.
The advance of the technology ecosystem creates inherent maintenance costs, even if you write bug-free software.
Keep in mind that software maintenance costs aren't only caused by engineering mistakes or new requirements: the world will shift around your software. You'll write a JavaScript library and it'll break in the next version of Node.js.
Or a Python version and it'll work in Python 3, but not in Python 4. You start with a perfect, modern library, and soon you'll have something that no longer runs on any modern computers. This is the reality of technology.
Since the next section will be about not reinventing the wheel, let me preface it by saying that sometimes it's a great idea to reinvent the wheel. Lots of big improvements in fundamental systems have been created by people who simply
wrote what they thought it should be, without consulting the prior art. And implementing basic software gives you valuable experience that you can't get if you only use it or build on top of it.
A critical failure of software culture is that nobody reads.
Binstock: You seem fastidious about always giving people credit for their work.
Alan Kay: Well, I'm an old-fashioned guy. And I also happen to believe in history. The lack of interest, the disdain for history is what makes computing not-quite-a-field.
Become familiar with the term Not Invented Here Syndrome and learn how to spot it: in many, many cases software is reinvented time and time again with loads of wasted effort, only because of local pride or a lack of research. Usually searching GitHub or Google for existing solutions to a problem will find some.
Most open source projects are the work of one contributor. One person has the problem, solves it, publishes the code, and attracts a few users. Sometimes they attract a crowd of users. As we'll discuss in nurturing contributors attracting anyone else to the project and keeping them there is a constant struggle.
When you create a new project that tries to do better than an old one, you decide not to increase the contributor base of the old project. Your contributions could have been the thing that gets that project over the hump, and the maintainer might have been planning on implementing something really similar but never got the time, and would have been overjoyed to accept you.
This isn't meant to be a guilt-trip. Sometimes you need to create a new project, even if there's an existing one. The maintainer might not readily accept pull requests, or might have a big difference of opinion. Or you might be trying to learn.
But if your goal is to make the most impact, contributing is often more important and more effective than creating something new.
Economically, we tend to think of sellers & buyers, customers & businesses, exchanges of value. Physical goods have per-unit costs that often make up a large part of the total cost of production. Even with the sunk costs of the factory finished, there's a big difference between building one car and building two.
Software doesn't have this attribute: the cost of distributing and copying digital works is usually too low to measure. Usually when people realize this, the reaction is joy - a hope for utopia. In the world of software, a few people can indeed make an outsized impact on the world. An iPhone game can make millions of dollars without requiring a factory or a team of salespeople.
But much like any product, the "parts cost" of open source is only a fraction of its actual cost to produce. Bandwidth can be free and distributing copies of the software can be instantaneous, but the marginal cost of each unit is dominated by two other costs: support and maintenance.
A lot of this book is devoted to kinds of support. Whether it's an IRC channel, an email, an issue tracker, a conference, or any other form of community, much of what happens in open source is support work. Whether it's helping people understand documentation, helping people who don't read documentation, giving advice about how to solve new problems, or diagnosing potential bugs, this is support work.
And it's likely that very early in a project's history, the time you dedicate to support will outweigh the time you spend writing code. Your software-writing time scales with the complexity of the project: your support time scales with the number of users and contributors you attract to the project. Very successful projects with thousands of users quickly accumulate hundreds of support issues.
Acquiring open source software usually doesn't involve any payment. There's no contract between you and your users, or between you and the people whose software you use.
But the buyer/seller relationship we have in everyday life automatically carries over into this world. People have expectations that software will work, that issues with software will quickly be fixed, and that you'll answer their questions.
This relationship is often the hardest part of software because it as some similarity with traditional buyer / seller relationships but substantial and important differences. With no payment or contract, you can't give an angry user a refund. You can't suggest they leave your store. You'll naturally be in the most empowered place to make the improvements your users want, but how are their needs expressed and received?
Of course, financial transactions aren't the only kind of value exchange. You might work on features in order to make your projects more popular, which leads to a better portfolio and reputation in the community. Reputation can lead to a better job or better positioning if you found a company. You might work on a feature in order to learn about the problem or acquire new skills.
There's no easy solution to this problem. BountySource is one potential route. It's a website that pools money and uses it to pay contributors to an open source project. Big projects like neovim with thousands of users but a relatively smaller developer group have successfully used BountySource to pay people for their time, so that developers are motivated and compensated to work on things that benefit lots of users but aren't necessarily fun, educational, or useful for building reputation.
'Open by default' is a pattern where people or groups decide to release all the code they write as open source, unless there are strong reasons not to. If you're open by default, you might keep your personnel file closed and maybe even key parts of a product, but everything else you publish, immediately, by default.
It's a popular idea amongst fans of open source. It's an idea I have promoted.
I no longer think 'open by default' is the right decision for most organizations.
There are lots of variables: if you're a government agency, you might have a requirement to open source your code. If you're in a huge private company, it might be a struggle to release a single line. Your company might require lots of software, or just one concentrated and valuable software product.
When I believed in 'open by default', I made several mistakes:
All in all, open sourcing a thing means taking responsibility for it. You're making a statement that the thing will be available, updated, and real. Leaving the project means abandoning the project. In the worst-case, if your personality veers toward guilt - and mine certainly does - this adds up and the responsibility is crippling. What is open source and why do I feel so guilty? is one view of this problem, from Jacob Thornton.
On the other end, open source makes a few things really hard:
Before something is published, it's easy to delete. Once it's on the internet, its removal means 404s, means upgrade paths, and spurned users. Famously a node.js developer deleted a module and it broken many other people's software. It's hard to shut things down, even if you have very good reasons to.
Similarly it's hard to fire users. Your project might get really really popular and you have responsibility. That responsibility doesn't mean money or fame, it just means responsibility. OpenSSL, for instance, an incredibly vital part of internet infrastructure, is developed by two guys named Steve, overworked, underpaid, and blamed for one of the worst security exploits ever.
The projects they're open sourcing are not just hackfest ideas or work that interns contribute, these are tools Facebook uses in production. Facebook open sources only what it uses in production—this way, people know that their offerings are supported and valuable.
Facebook's open source policyis to only open source code that it actually deploys. My equivalent is to only open source code I use.
Hi Reader!
Email is traditionally the only medium where both greetings and a signature is still expected. Text messages, for instance, rarely begin with "Hello Julia, I hope you're having a great day", unless they come from your parents. The same goes for GitHub tickets: maybe because there's always a username and an avatar on the top, it's rare to see actual greetings and email-style communication style.
This makes the genial voice a sort of cheat-code for improving communications. Write in the genial voice using people's first names and friendly introductions and you might be perceived as a square, but more often than not, people's responses are friendlier. Sometimes people will even follow your lead and respond in the same style.
Technically, the genial voice makes your signals of friendliness redundant - the friendly greeting and goodbye will benefit from the serial position effect and stay in someone's memory, giving you a better impression on average.
Contributions are a wonderful thing: waking up to someone liking your work and deciding that they want to help build a project is a great feeling.
Many contributions are easy to judge: someone fixes an issue or adds a feature that's clearly within the scope of the project and all you have to do is a round or two of code review and the contribution is in. Saying yes to contributions is easy and satisfying.
Let's talk about saying no.
Why say no to someone who just spent their own time trying to help you? It's a common rookie mistake to never say no - to allow everyone collectively to guide the scope of your project and accept changes with little hesitation. But any amount of time as a maintainer and project manager will make you aware of the importance of keeping a tight scope. And if you spend time reading contributions, you'll find that most of them have issues, some of which cannot be resolved.
Here are some pull requests that I've personally had to reject:
Rejection is hard. There are a few key things you can communicate to soften the blow. Like many of the other things I recommend, the underlying strategy is that you need to be explicit about the positive and emotional parts of an encounter, not just the technical parts. It's simple and easy to deliver a code review, but implicit in that review is the fact that someone took the time to contribute, and that should be recognized as well.
When someone contributes to open source, or helps anyone else, they're giving their time willingly to support others. They could have kept a private fork, or kept to themselves, but instead they chose to be helpful.
So even if a contribution has quality issues or is something you completely disagree with, say thanks. For instance:
Hi Suzie,
Thanks for opening this pull request!
Note that this is using Genial Voice: see the chapter on Genial Voice for an explanation of how & why.
Take the example of porting a project from one language to another. In my case, it was from JavaScript to CoffeeScript - languages with a sometimes-antagonistic relationship.1 CoffeeScript fans believe the language is simpler, JavaScript fans believe their language is more direct. The delivery of CoffeeScript PRs often comes with a mission statement that reflects that divide. Similarly with pull requests to add Bower support to JavaScript modules that work in the browser - the Bower & NPM communities are somewhat ideologically divided.
Interactions around these contributions can fall into the trap of reflecting the community arguments. You can avoid this with a simple trick: acknowledging needs as valid.
When someone contributes a patch, it's because they have some need. Simply say that you acknowledge that needs, and you're instantly in a much better place:
Thanks for the contribution! I appreciate the effort to make this project more accessible by porting it to CoffeeScript, and it's very cool to see it in this language. I'd like to keep it in JavaScript, though, because that's the language I'm comfortable with.
Rejected pull requests aren't a dead end, so don't make them sound like the end. You should encourage everyone to contribute again, and present their options explicitly:
I'm going to close this pull request, but I hope you can contribute in the future! If you need this change, feel free to maintain a fork.
Not just in technology but in the wider world, criticism is explicit and praise is implied. Issue trackers track bugs, features requests, and complaints - not usually the cases where things go well. Many projects only get warm fuzzies through the proxy of the 'Star' button, which lacks the humanity that makes people really feel good in a lasting way.
Let's talk about everything except for software development. Sometimes the image of a software developer is a person typing, alone, all day long. In most cases, programming consumes less than half your actual work time, even if that's your job description. Some of that is hated busy-work, some of it is social interaction that keeps you sane, some of it is akin to emotional labor.
Technology changes and every project is unique but there are common components to this work, like interacting with people, supporting and critiquing the work of others, and explaining your craft.
Let's find the parts in common and pick ways of expressing them that are both productive and kind.
If you've read a section with an example script - an example of what you should say to be extremely nice in response to some situation - you'll notice that the nice version is usually a lot longer than the default. You can type "Duplicate #142" really quickly, but not something like:
Thanks for posting this issue! It's a valid concern, and we're already tracking it in a previous issue, #342. I'm going to close your issue now to keep the discussion in one place. If you have any further input on the main issue, #342, please post it there.
Here it's a good idea to steal a trick from professional customer support teams: use snippets. Software like TypeItForMe and TextExpander let you type short abbreviations like ;close, which expand to long pieces of prewritten text - and even support token replacement, so you can replace custom parts of the text, like the issue number.
For a comic perspective on emotional labor, check out the
emotional labor Chrome extension. What I'm talking
about here is the social expectation for people to show warmth or cheeriness in certain situations or professions - like the American expectation that baristas should smile.
If you haven't given up the dream of writing bug-free software, I suggest you do so now. Accepting that all things are flawed will make bug reports feel like a blessing, not a curse, and will alleviate some of the
stress they can cause.
Now let's get in to bug reports.
If you're lucky, the person reporting a bug has read the polite.technology guide. But in most cases, sadly, they won't have, and that leaves you with a few predictable cases:
Bug reports and, in fact any sort of support work, involves a lot of clarification.
Setup matters. The difference between a warning and an error, between Internet Explorer 8 and 10, is vast for a developer: knowing a person's browser and the quirks of their setup will immediately give a few clues for the cause.
You need to know, precisely, what's the problem. Most bug reports lack detail of what's going wrong: does broken mean that the screen is blank, or that something is rendered slightly incorrectly?
It's wise to get clear answers first, rather than guessing about the user's setup or the problem they're encountering. Here's an example script:
User:
I've installed your software and it's totally broken.
Developer:
Thanks for the bug report! To make this easier for me to diagnose, could you please say more about what browser you're using, what you are trying to do, what you expect the library to do, and what happens instead? If possible, provide a JSFiddle or include some of your relevant code - that would make this problem much easier to pin down.
Duplicate issues are a fact of life: even people who search for existing issues often can't find them because they'll use different words. But being the maintainer, you will likely have a mental list of all the popular issues, and have to close the same recurring issues repeatedly.
When this happens, resist the impulse to be short, and instead follow this friendlier script:
Instead of:
Duplicate #342
Try:
Hi Jane!
Thanks for posting this issue! It's a valid concern, and we're already tracking it in a previous issue, #342. I'm going to close your issue now to keep the discussion in one place. If you have any further input on the main issue, #342, please post it there.
Thanks!
Once a project achieves a certain level of success, it will have users, and those users will have additional demands of the project in the form of feature requests. Experienced and empathetic users will state their feature requests precisely and kindly, but others will use an unfriendly tone or imprecise language that doesn't lend itself to a solution.
Ignoring the first principle will lead to burnout: there are unlimited features to be requested and limited time to implement them. The sense of obligation quickly becomes an emotional burden.
Ignoring the second principle will damage the project
and reduce its chances of ever attracting additional contributors, which is the only way to succeed in the long term.
software will try to fix and those it will not.
practices are used, which language.
People often ask for estimates - when will a bug be fixed, when will a feature be implemented? This is totally reasonable from their side, since they might be waiting for a bugfix to launch a product. Lots of people asking you for estimates at the same time can be overwhelming and seem like overstepping, but you don't need to take out your frustration on each one of them: instead you can use a form response:
I'm working on it right now, but I'd happily accept a Pull Request to speed this up. This is a relatively big project, with lots of work to do, and we could really use more contributors!
Or:
Unfortunately I'm quite busy right now and I don't know when I'll get the time to finish this. I'll happily accept a Pull Request to implement this feature if you can find the time to do it yourself!
A common thread between successful ways to respond to bug reports, feature requests, and communications in general is to acknowledge concerns as valid. This can be tricky, because often people will immediately present a concern, a potential solution, their emotions, and other signals, all at the same time. It's important to read carefully to observe each element and respond to each element carefully, rather than discounting or accepting statements in their totality.
For instance, let's say that you have a user who is interacting with your JavaScript library, and they call a function that expects text as an argument but they provide it with a number. After hours of struggling with this problem and cursing your library and everything else, they realize this problem and write an impassioned ticket:
Ugh, well you just wasted ten hours of my time. Why is this library so strict about the types of data it accepts? Can't you just convert everything to strings - that's probably quick to do.
- Disappointed in Denver
You get this ticket at 8 in the morning on a Monday, and the signals cross:
So you have multiple signals, and multiple options for how to respond to and categorize them. Should you hastily close the ticket and insist that they need to read the documentation? Make it clear that your time isn't theirs, and changing your library would be a terrible idea?
Probably not - that would only escalate the conflict, making a frustrated person even more frustrated.
Here's a vital script to follow:
I see that this cost you a bunch of time. I understand that this was confusing to debug and the library didn't work the way you expected it to. I'm sorry that it was such a tough time.
The gist is simple:
Maintaining an open source project, like other jobs that are public and often involve a lot of work, can be mentally draining. Staying focused and stable is difficult, but easier with a few good habits:
As the maintainer of a project, you can guide conversations and keep them civil and productive, and take action when they aren't.
A conversation is derailed when it starts out as a friendly exchange but becomes focused on other issues or loses its civility.
You can initially try to keep a discussion on topic by re-asking or re-stating the original post in different words. People who discover the thread will read your on-topic comment and get back on topic.
If the discussion touches on a new, but different, topic, encourage participants to create another thread, so that the original thread can stay focused.
Just like politics, it's best to exhaust the diplomatic options before considering the rest.
Make sure you understand what someone is angry about.
Ask questions about what's wrong and what could be improved. Showing interest make the person feel heard, and often the actual problem at stake is different from what it first appears to be, and can be easier to solve. The X-Y problem describes one of these cases, and is a great read. Entire wars can be fought based on misunderstandings: asking clarifying questions is a good idea.
Disagreements with collaborators call for more time investment and a different approach: one of the best options to is to get on a phone, video chat, or meet in person. Seeing emotional cues makes conversations easier, and a lot of times meeting in person will reveal the background of why someone is feeling a certain way and saying things. It seems to you that they're being opinionated and reckless, but maybe they have to hit a deadline for work and have a baby to take care of.
If you can, face problems one-on-one at first, whether it's via chat, email, or in person. The privacy of a personal conversation makes people less defensive and more amenable to change, and also ensures that you don't 'make an example' of someone and establish a pattern of fighting in a community.
If social means fail, a GitHub issue tracker gives you several levels of control:
There are multiple ways of seeing your project. Is it a free space with you as the de-facto leader? Do you fight for people's right to say anything within legal boundaries, or are you an active moderator? What is your responsibility to create a caring community?
One opinion is well-summarized by Anil Dash: moderation is part of running a community of any kind. Active moderation has a good track record.
While the shape of your community won't be a perfect reflection of its rules, there is some degree of correspondence with the presence and type of Code of Conduct you choose, assuming you choose one.
For instance, The Contributor Covenant mentions:
It doesn't simply say "don't troll", and it goes far beyond what's legal or illegal. The rules themselves specifically call for a positive environment, not just a safe one.
Building a larger contributor base is one of the most important and most difficult goals of open source software. With four or five people working on a project and taking ownership of its success, you have a more resilient project, more ideas in the mix, and greatly reduced stress.
But establishing that size of a contributor pool can be difficult: while bug reports flow in, Pull Requests are rarer and usually fix a specific problem that a user is running into. And the combination of free time and motivation required for open source work can be hard to come by, when everyone has day jobs and other priorities.
So contributions are valuable and contributors are amazing, and you should praise and hang on to them.
People who start contributing to open source usually have a grain of enthusiasm already. Your job as the existing contributor is to nurture that bit of enthusiasm into something bigger.
Here's an example of an especially friendly thank-you:
Thanks so much for this PR! It's such a big lift for this project and I
really appreciate you taking the time to make it. Hope to see you around!
All successful projects will require supporting users, regardless of how much documentation is provided. Really successful projects can include a lot of support work - enough that companies can make a business out of answering support emails and calls.
You might really like providing support, or you might dread the idea of having to interact with people. For understanding the technical problems you're solving, support is a great way to do informal research. Recurring issues in support or concepts that users don't get from documentation should inform improvements.
If you're using GitHub, use issue templates. They let you pre-populate the form that users fill out to report a bug: giving their messages more structure makes them more likely to be answerable.
There are some cases where you won't want to open yourself to support requests - if a project is very successful but you don't have time to work on the issue queue, or if it's very technical and there's very little support load. In these cases, you may want to either:
Things that I read