Add Troubleshooting section

troubleshooting/burnout.md

@@ -0,0 +1,43 @@
+---
+title: Feeling guilty or burned out
+---
+
+Open source work once brought you joy. Maybe now it’s starting to make you feel avoidant or guilty. Perhaps you’re feeling overwhelmed or a growing sense of dread when you think about your projects. And meanwhile, the issues and pull requests pile up.
+
+Burnout is a real and pervasive issue in open source work, especially among maintainers. Let’s talk about how to make things better.
+
+## Clearly communicate your limits
+
+Most people who come across your project don’t know anything about you or your circumstances. They may even think that you get paid to work on the project, especially if it’s something they regularly use and depend on.
+
+Maybe at one point you put a lot of time into your project but now circumstances have changed. You’re juggling a new family and a full-time job, and you just don’t have that much time to spend on open source work anymore. That’s perfectly okay! Make sure other people know about it. Other people won’t know what’s happening in your life unless you tell them.
+
+Write your time constraints directly into your README. If your time is purely volunteered, make sure that people are aware of your circumstances. You can even tell them exactly how many hours you spend on the project per week, or let them know which days you’re most active. If your project is completely unmaintained or a low priority in your life, tell people that, too. (You can read more about proactive communication under **"Best Practices for Maintainers" (link)**.)
+
+## Write an agreement for maintainers and contributors
+
+If you haven’t noticed by now, the more you write down, the easier your life will be. 😎  One thing you may want to consider writing down are ground rules and expectations for maintainers (and contributors!). Think of it as an extension of your code of conduct.
+
+For example, as a maintainer, you might promise to acknowledge every contribution, even if you don’t accept them. You might ask contributors to promise that their code passes all tests before they submit it.
+
+[Jekyll](https://github.com/jekyll/jekyll/pull/5011/files), [CocoaPods](https://github.com/CocoaPods/CocoaPods/wiki/Communication-&-Design-Rules), and [Homebrew](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Maintainers-Avoiding-Burnout.md) are several examples of projects that have ground rules for maintainers and contributors.
+
+## Don’t forget to take breaks
+
+Although it should go without saying, take a vacation! Sometimes it can be hard to take a break from open source work when it feels like everybody is depending on you. People may even try to make you feel guilty for stepping away.
+
+Do your best to find support for your users and community while you’re away from a project. If you can’t find the support you need, take a break anyway. Be sure to communicate when you’re not available, so people aren’t confused by your lack of responsiveness.
+
+Taking breaks applies to more than just vacations, too. If you don’t want to do open source work on weekends, or during work hours, communicate those expectations to others, so they know not to bother you.
+
+## If you can’t manage your project, let someone else take over
+
+There’s no shame in admitting when you don’t have the bandwidth to care for your project anymore. If other people are enthusiastic about its direction, however, give them commit access or formally hand over control to someone else. If someone forked your project and is actively maintaining it elsewhere, consider linking to the fork from your original project. Take it as a compliment that so many people want to see your project live on!
+
+Further reading:
+
+* [http://progrium.com/blog/2015/12/04/leadership-guilt-and-pull-requests/](http://progrium.com/blog/2015/12/04/leadership-guilt-and-pull-requests/) 
+
+* [https://archive.is/j8zAk](https://archive.is/j8zAk) 
+
+* [https://publicobject.com/2016/05/03/the-open-source-maintainers-dilemma/](https://publicobject.com/2016/05/03/the-open-source-maintainers-dilemma/)

troubleshooting/conduct.md

@@ -0,0 +1,63 @@
+---
+title: Enforcing your code of conduct
+---
+
+Your code of conduct helps create a healthy and constructive social atmosphere for your project’s community. Sometimes, despite your best efforts, somebody will do something that violates this code. In this section, we’ll talk about how to address negative or harmful behavior in your project’s community.
+
+## Write down how you’ll enforce your code of conduct
+
+Ideally, you’ve explained how your code of conduct will be enforced **_before_** a violation occurs. There are several reasons for this:
+
+* Tying values to action turns the code of conduct from a philosophy into a policy. It demonstrates that you are serious about enforcing the code of conduct.
+
+* You will empower your community by explaining how to report a violation and assuring them their complaint will be reviewed.
+
+* Community members will feel reassured that there is a clear review process if they are ever investigated for a violation. As with any other aspect of managing an open source project, transparent communication helps prevent decisions from being made by a few people behind closed doors.
+
+You should give people a private way (such as an email address) to report a code of conduct violation and explain who receives that report. It could be a maintainer, a group of maintainers, or a code of conduct working group.
+
+Don’t forget that someone might want to report a violation about someone who usually receives those reports. In this case, give them an option to report violations to someone else. For example, [@ctb](https://github.com/ctb) and [@mr-c](https://github.com/mr-c) explain on their project, [Khmer](https://github.com/dib-lab/khmer):
+
+*Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by emailing **khmer-project@idyll.org** which only goes to C. Titus Brown and Michael R. Crusoe. To report an issue involving either of them please email **Judi Brown Clarke, Ph.D.** the Diversity Director at the BEACON Center for the Study of Evolution in Action, an NSF Center for Science and Technology.* [1]
+
+## Gather information about the situation
+
+Treat each community member’s voice as important as your own. If you receive a report that someone has violated the code of conduct, take it seriously and investigate the matter, even if it does not match your own experience with that person. Doing so sends a signal to members of your community that you value their perspective and trust their judgment.
+
+The community member in question may be a repeat offender who consistently makes others feel uncomfortable, or they may have only said or done something once. Both can be grounds for taking action, depending on context.
+
+Before you respond, give yourself time to understand what happened. Read through the person’s past comments and conversations to better understand who they are and why they might have acted in such a way. Try to gather perspectives from other community members about this person and their behavior.
+
+## Take appropriate action
+
+When you feel you sufficiently understand the context of the situation, you’ll need to decide what to do. As you consider your next steps, remember that your goal as a moderator is to foster a safe, respectful, and collaborative environment. Consider not only how to deal with the situation in question, but how your response will affect the rest of your community’s behavior and expectations moving forward.
+
+Here are some ways you might respond to a code of conduct violation:
+
+* Give the person in question a public warning and explaining how their behavior negatively impacted others, preferably in the channel where it occurred. Where possible, public communication helps convey to the rest of the community that you take the code of conduct seriously. Be kind, but firm in your communication.
+
+* Privately reach out to the person in question to explain how they violated the code of conduct and how their behavior negatively impacted others. You may want to use a private communication channel if the situation involves sensitive personal information. If you communicate with someone privately, it’s a good idea to CC those who first reported the situation, so they know you responded. Ask the reporting person for consent first before CCing them into your response.
+
+Sometimes, a resolution cannot be reached. The person in question may become aggressive or hostile when confronted or does not change their behavior. In this situation, you may want to consider taking stronger action. For example:
+
+* Suspend the person in question from the project, enforced through a temporary ban on participating in any aspect of the project
+
+* Permanently ban the person from the project
+
+Banning members should not be taken lightly and represents a permanent and irreconcilable difference of perspectives. You should only take these measures towards a community member when it is clear that a resolution cannot be reached. 
+
+It’s not always easy to enforce your code of conduct, but this type of work is necessary to maintain a healthy and active community. When a project seems hostile or unwelcoming, even if it’s just one person whose behavior is tolerated by the rest of the community, you risk losing the contributions of many others, some of whom you may never even meet.
+
+### Footnotes
+
+[1] [https://github.com/dib-lab/khmer/blob/master/CODE_OF_CONDUCT.rst](https://github.com/dib-lab/khmer/blob/master/CODE_OF_CONDUCT.rst) 
+
+### Further reading
+
+* [https://www.djangoproject.com/conduct/enforcement-manual/](https://www.djangoproject.com/conduct/enforcement-manual/)
+
+* [http://www.slideshare.net/aeschright/enforcing-your-code-of-conduct-effective-incident-response](http://www.slideshare.net/aeschright/enforcing-your-code-of-conduct-effective-incident-response) 
+
+* [https://www.rust-lang.org/en-US/conduct.html](https://www.rust-lang.org/en-US/conduct.html) 
+
+* [http://producingoss.com/en/producingoss.html#difficult-people](http://producingoss.com/en/producingoss.html#difficult-people)

troubleshooting/contributions.md

@@ -0,0 +1,33 @@
+---
+title: Handling contributions you don't want to accept
+---
+
+As a maintainer of an open source project, you’ll inevitably receive contributions that you don’t want to accept. Maybe the contribution changes your project’s scope or doesn’t match your vision. Maybe the idea is good, but the execution is poor.
+
+Regardless of the reason, here are some strategies to tactfully handle contributions that don’t meet your project’s standards.
+
+## Say something!
+
+If you receive a contribution you don’t want to accept, your first reaction might be to ignore it or pretend you didn’t see it. Doing so could hurt the other person’s feelings and even demotivate other potential contributors in your community.
+
+Contributing to an open source project can be intimidating, especially if it’s someone’s first time. Even if you don’t accept their contribution, be sure to respond to their submission. Acknowledge the person behind it and thank them for their interest. It’s a big compliment! If you don’t want to accept the contribution, clearly explain why and offer suggestions for improvement if you’re able.
+
+## Write down what you won’t accept beforehand
+
+Having a clear contribution policy helps depersonalize situations where you don’t want to accept a contribution. Saying "Your contribution doesn’t match this project’s criteria" feels less personal than “I don’t like your contribution”. In addition, clear contribution policies can reduce the chances that someone will submit something you don’t want in the first place. 
+
+## Ask that people discuss major changes first
+
+In your contributing guide, explain your project’s process for submitting and accepting contributions. Many projects specify that if someone is proposing a major change, that they open an issue first before doing any work. This policy reduces the chances that someone will put in many wasted hours of work into a pull request that you aren’t going to accept. And, if someone does make an unexpected pull request, you can point to your policy and say that major changes need to be discussed first.
+
+## Require tests and other checks to improve the quality of code
+
+Require that all code contributions pass your tests before they can be submitted. You’ll help set a minimum standard of quality for all submissions. You can also emphasize the use of style guides, linters, and other tools to help people meet your quality standards.
+
+## Mentor or find a mentor for your contributor
+
+Maybe someone in your community regularly submits contributions that don’t meet your project’s standards. It can be frustrating for both parties to repeatedly go through rejections.
+
+If you see that someone is enthusiastic about your project, but needs a bit of polish, be patient. Explain clearly in each situation why their contributions don’t meet the expectations of the project. Try pointing them to an easier or less ambiguous task, like an issue marked "good first bug," to get their feet wet. If you have the time, you can even mentor them through their first contribution, or find someone else in your community who might be willing to mentor them.
+
+Ultimately, if a contribution isn’t good enough, remember that you are under no obligation to accept it. Be kind and responsive when people contribute to your project, but only accept changes that you truly believe will make your project better.

troubleshooting/finding-consensus.md

@@ -0,0 +1,57 @@
+---
+title: Finding community consensus
+---
+
+Early in the life of your open source project, making major decisions is easy. When you want to do something, you just do it.
+
+As your project becomes more popular, more people will take interest in the decisions you make. Even if you don’t have a big community of contributors,, you’ll find that people will start to weigh in on your decisions or raise issues of their own if your project has a lot of users.
+
+For the most part, if you’ve cultivated a friendly, respectful community and documented your processes openly, you and your community should be able to reach a resolution. But sometimes you run into an issue that’s a little bit harder to address. Here are some strategies to reach consensus.
+
+## Set the bar for kindness
+
+When your community is grappling with a difficult issue, tempers may rise. People may become angry or frustrated and take it out on one another, or on you.
+
+Your job as a maintainer is to keep these situations from escalating. Even if you have a strong opinion on the topic, try to take the position of a moderator or facilitator, rather than jumping into the fight and pushing your views.
+
+Remember that others in your community are looking to you for guidance. Set a good example for others. You can still express disappointment, unhappiness, or concern, but do so with a sense of calm and detachment. Keeping your cool isn’t easy, but your leadership will improve the health of your community. The internet thanks you. 🙏
+
+## Focus on the journey, not the destination
+
+Some projects use a voting process to make major decisions. While sensible at first glance, voting can emphasize getting to an "answer," rather than listening to and addressing each other’s concerns. Voting can also become political, where community members feel pressured to do each other favors or vote a certain way.
+
+As much as you are able, emphasize "consensus seeking" rather than consensus. Under a consensus seeking process, community members discuss major concerns until they feel they have been adequately heard. When only minor concerns remain, the community moves forward. A consensus seeking process acknowledges that a community may not be able to reach a perfect answer. Instead, it prioritizes listening and discussion.
+
+Even if you don’t actually adopt a consensus seeking process, as the maintainer of your project, it’s important to make sure that people know you are listening. Making other people feel heard and committing to resolving their concerns can go a long way in diffusing a sensitive situation. Then, follow up on your words with actions.
+
+Don’t rush into a decision for the sake of having a resolution. Make sure that everybody feels heard and that all information has been made public before moving toward a resolution.
+
+## Keep the conversation focused on action
+
+While discussion is important, there is a difference between productive and unproductive conversations. Encourage discussion so long as it is actively moving towards resolution. If it’s clear that conversation is languishing or going off-topic, jabs are getting personal, or people are quibbling about minor details, it’s time to shut this thing down.
+
+Allowing these conversations to continue is not only bad for the issue at hand, but bad for the health of your community. It sends a message that these types of conversations are permitted or even encouraged, and it can discourage people from raising or resolving future issues.
+
+With every point made by you or by others, ask yourself, *"How does this bring us closer to a resolution?"* If the conversation is starting to unravel, ask the group, *“Which steps should we take next?”* to refocus the conversation.
+
+If a conversation is taking place on an Issue that clearly isn’t going anywhere, there are no clear actions to be taken, or the appropriate action has already been taken, close the Issue and explain why it has been closed.
+
+## Pick your battles wisely
+
+Context is important. Consider who is involved in the discussion and how they represent the rest of the community. Is everybody in the community upset about, or even engaged with, this issue? Or is a lone troublemaker raising the issue? Remember to consider your community members who are silent, not just the active voices.
+
+A notable exception to this framing is when the issue concerns community behavior or governance. In this case, consider whether addressing the issue makes your community healthier or less healthy. A community’s health involves not just the people who are in your community right now, but people you may never hear from because they don’t feel comfortable joining or participating. Healthy and welcoming communities help ensure a future for your project by encouraging active contribution. Unhealthy communities threaten the life of your project and will leave you feeling stressed and unhappy.
+
+If the issue does not represent the broader needs of your community, you may just need to acknowledge the concerns of a few people. If this is a recurring issue without a clear resolution, point them to previous discussions on the topic and close the thread.
+
+## Identify a community tiebreaker
+
+With a good attitude and clear communication, most difficult situations are resolvable. However, even in a productive conversation, there can simply be a difference in opinion on how to proceed. In these cases, you should identify an individual or group of people that can serve as a tiebreaker. A tiebreaker could be the primary maintainer of the project, or it could be a small group of people who make a decision based on voting. Ideally, you’ve identified your tiebreaker and the associated process in your GOVERNANCE.md before you ever have to use it.
+
+Your tiebreaker should be a last resort. Divisive issues can be an opportunity for your community to grow and learn. Embrace these opportunities and try to use a collaborative process to move to a resolution wherever possible.
+
+### Further reading
+
+* [http://producingoss.com/en/producingoss.html#common-pitfalls](http://producingoss.com/en/producingoss.html#common-pitfalls) 
+
+* [https://en.wikipedia.org/wiki/Consensus-seeking_decision-making](https://en.wikipedia.org/wiki/Consensus-seeking_decision-making)