This is a preview of Polite Technology: sign up to get an update once it's finished:
In software and especially in open source software, so-called "people skills" are underemphasized.
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.
Specifically this is about creating open source software. Open source software, loosely defined, is software that is free to share. 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. Because 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 most 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, as well as 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.
Table of Contents
- Brief sidenote about culture
- A brief introduction to me
Brief sidenote about culture
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 techniques covered in this book may seem old-hat. Others may be a major adjustment. We're trying to establish best practices: tried and true techniques for dealing with a variety of situations in ways that agree with many types of people.
A brief introduction to me
Hi, I'm Tom. I've worked on many open source projects over the span of over ten years. Some projects have taken off and acquired a life of their own. Others have failed. Some have 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. But technically brilliant people can't survive alone. People who can build communities and work productively with other people can be more successful than those with supernatural coding skills.
- Scope: a scope is a definition of the goals and problems that are considered by a project to be vital. Project management includes the task of defining scope, which is setting these goals and excluding tasks and ideas that are declared to be irrelevant to the project; i.e. "out of scope".
- Roles Maintainer: someone who is responsible for a project in some way. A maintainer is usually a programmer who consistently writes or improves the code, but can also be a writer who works on documentation or a person who maintains the workings of the community, like responding to support issues. Contributor: someone who has spent some time on a project and added code, documentation, or something else, but is may not be a permanent presence and has no implied responsibility. * User: someone who has used a project and may post issues or feature requests.
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.
Describe your configuration
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:
- Browser & Version
- Browser extensions, if any
- Operating System
For installed software and libraries, there are some other things to report:
- How you installed the software: as a download, from a package manager, or from source
- Interpreter or compiler version: are you using Python 2 or 3, or node.js v0.4.0 or v0.6.0?
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.
Provide an example
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.
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.
Specifically say what is wrong
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.
Use a bug tracker
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 for & subscribe to existing issues
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.
Responding to bug reports
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:
Asking for clarification
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:
I've installed your software and it's totally broken.
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.
Closing duplicate and irrelevant issues
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:
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.
Why Reporting Bugs is So Hard
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.
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:
- Automated tests, and the rule that all new code contributions need to pass existing tests or add new tests
- Code style checks, that confirm that new code follows the existing opinionated code style
- Codes of conduct, that define socially unacceptable behavior and the ways a maintainer can respond do it
- Licenses, that define what kinds of uses and adaptations of source code or other stuff is legal
Why create rules?
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.
Codes of Conduct are cultural rules.
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.
Licenses are legal rules.
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.
Intent and time commitment
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.
Consequences of building a thing you can't maintain, don't need, or duplicates an existing effort
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.
If you're writing code for the sake of learning, accept it as that
Because 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.
Help projects attain critical mass
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, growing a project from one contributor to two or more is the central struggle of open source.
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 accept pull requests, or might have a big difference of opinion. You might be trying to learn.
But if your goal is to make the most impact, contributing to an existing project can be more effective than creating something new.
The Buyer / Seller Relationship
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.
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.
Gamified indicators tell a simple story
If you look at a site like GitHub, it is gamified in some obvious ways:
- Stars quantify interest in a project. They're like a bookmark or an 'upvote', saying that someone likes a project.
- Forks count how many people might be adapting your software into something new.
- Issues show how many people 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.
Keys to success
- Communicating clearly
- Defining the problem
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.
Defining the problem
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.
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.
Rejecting pull requests
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:
- A potential contributor likes a different language than the one I chose, so they port the project from one language to the other.
- TODO: Someone who misread documentation contributes a rewrite of the documentation specifically designed to preclude their conclusion, but that introduces other problems.
- Someone wants a feature that wasn't in my initial scope and won't be something that I use, so I wouldn't feel comfortable maintaining it.
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.
Always begin with thanks
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:
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.
Acknowledge needs as valid
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:
Present the ways out
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.
Maintaining open source software
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.
Automating emotional labor
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.
Responding to feature requests
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.
- The maintainer does not owe their time to anyone
- The maintainer must treat everyone with respect
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.
- Maintainers are the keepers of the project principles
- The goal of the software.
- The scope that defines problems that the software will try to fix and those it will not.
- The style of the project: which programming practices are used, which language.
- The culture by which the project is managed.
- Maintainers approve of changes to the software by these principles, and also manage discourse and which other contributors are allowed.
When will this be done?
People often ask for estimates - when will a bug be fixed, when will a feature be implemented? This is totally reasonable from their side, because 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!
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!
Acknowledging concerns as valid
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.
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:
- This poor fellow did indeed have a tough time completing their task. They might have been on a deadline or might have a baby keeping them up at night, and they would have had a much easier time if your library worked the way they expected it to.
- But they're recommending something that'd make your library worse - automatically turning numbers into text makes its behavior more complex and less predictable in a way that you don't want to live with.
- And they're also making a broad statement about how 'easy' it would be to implement the change and insisting that you do it promptly - why do they feel entitled to your time?
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:
- I see that you are feeling a certain way
- And those feelings are valid
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.
Moderating tough conversations
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:
- You can edit & delete other people's comments in your repositories. If someone uses expletives or other language, you can edit their response down to the useful bits.
- You can block threads that have been derailed
- You can block and report repeatedly abusive users
Your space to moderate
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:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
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.
Building contributor skills
- Guide and teach people by giving great code reviews
- When you set a policy for contributing to your project, like requiring a pull request for each feature, follow it yourself. Show the thinking behind your changes.
Building contributor enthusiasm
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.
- Be generous in your praise
- If you have to go through code reviews, help when necessary and help them understand the goal, so that they don't feel like they'll never be done.
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:
- Create a rule specifying that the Github issue tracker is only used for bug reports, feature requests, or other discussion - not support inquiries - and encourage people to use another site for support, like StackOverflow.
- Disable the issue tracker entirely and encourage people to communicate by writing code - by submitting PRs. Recently several maintainers have done this, with Ryan Florence writing about it.
Things that I read
- Isaac Schlueter: Building Compassionate Communities in Tech (2013)
- That talk clued me into
- Getting Help with Open Source: Just a few bits by Chris Schmidt (2007)
- Open Source Guilt Slides and Open Source Guilt Presentation by Jacob Thornton (fat)
- Idiomatic Contributing by Jon Schlinkert
- My Condolences, You're now the maintainer of a popular open source project by Daniel Bachhuber
- Empathy in Engineering by Kimberly Munoz
Tools you can use to enhance your politeness
- Foxtype's politeness checker attempts to automatically check polite English
- How to write good bug reports, by Geoff Greer
- Sustainable Open Source, about the pattern of overwork and burnout amongst popular open source projects
- If your website is full of assholes, it's your fault by Anil Dash
- Non-Violent Communication is the inspiration for many of the communication techniques.
- How to Contribute to an Open Source Project on GitHub: a screencast series that demonstrates the basics of git, pull requests, and issues