From 2889c7ad58f4cbe507cb0972ec1a9ebc45d301d1 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Wed, 17 Aug 2016 16:18:59 -0500 Subject: [PATCH 1/2] Replace fancy quotes with plain ol' boring quotes --- README.md | 2 +- docs/content-model.md | 32 ++++++++-------- docs/personas.md | 12 +++--- getting-started/branding.md | 24 ++++++------ getting-started/index.md | 16 ++++---- getting-started/legal.md | 32 ++++++++-------- getting-started/preparing.md | 30 +++++++-------- getting-started/setting-expectations.md | 24 ++++++------ index.md | 4 +- marketing/building-community.md | 18 ++++----- marketing/index.md | 4 +- marketing/measuring.md | 26 ++++++------- marketing/spreading-word.md | 22 +++++------ sustaining/best-practices.md | 50 ++++++++++++------------- sustaining/healthy-communities.md | 32 ++++++++-------- sustaining/index.md | 2 +- sustaining/leadership.md | 32 ++++++++-------- troubleshooting/burnout.md | 28 +++++++------- troubleshooting/conduct.md | 18 ++++----- troubleshooting/contributions.md | 22 +++++------ troubleshooting/finding-consensus.md | 22 +++++------ troubleshooting/getting-paid.md | 10 ++--- troubleshooting/index.md | 4 +- 23 files changed, 232 insertions(+), 234 deletions(-) diff --git a/README.md b/README.md index 3d236811c34..85e4cf921a6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Open Source Handbook -This handbook is a collection of resources to help individuals, communities, and companies sustainably embrace open source software. It explains not only how to accomplish a task, but why you’d want to, and how that task fits into the larger story of consuming, contributing to, and producing open source software. +This handbook is a collection of resources to help individuals, communities, and companies sustainably embrace open source software. It explains not only how to accomplish a task, but why you'd want to, and how that task fits into the larger story of consuming, contributing to, and producing open source software. This handbook aims to foster healthy open source communities, and provide a canonical place for the community to discuss and codify best practices into highly-approachable resources. diff --git a/docs/content-model.md b/docs/content-model.md index ccad8adc78f..adde52799c9 100644 --- a/docs/content-model.md +++ b/docs/content-model.md @@ -1,6 +1,6 @@ # Content Model -The Open Source Handbook helps individuals, communities, and companies embrace open source software. It explains not only how to accomplish a task, but why you’d want to, and how that task fits into the larger story of consuming, contributing to, and producing open source software. +The Open Source Handbook helps individuals, communities, and companies embrace open source software. It explains not only how to accomplish a task, but why you'd want to, and how that task fits into the larger story of consuming, contributing to, and producing open source software. This content is created and curated by GitHub, and covers topics that are very relevant to GitHub users, but it is not specific to GitHub products. @@ -13,22 +13,22 @@ For content that is specific to GitHub products, see: Each piece of content is grouped under a *dimension* and *topic*. -A *dimension* roughly describes an individual’s relationship with an open source project: +A *dimension* roughly describes an individual's relationship with an open source project: 0. **Basics**: rudimentary introduction to the concepts of open source. 0. (coming in v2) **Consuming**: using open source software. 0. (coming in v2) **Contributing**: getting involved and improving existing open source projects. 0: **Producing**: starting, growing, and maintaining your own open source project. -A “topic” groups together content around a high-level goal of the user, and should begin with a [gerund](https://en.wikipedia.org/wiki/Gerund). +A "topic" groups together content around a high-level goal of the user, and should begin with a [gerund](https://en.wikipedia.org/wiki/Gerund). Examples: -- :smile: “Building a community” -- :smile: “Reviewing contributions” -- :smile: “Choosing a license” -- :cry: “Code review” -- :cry: “Legal” +- :smile: "Building a community" +- :smile: "Reviewing contributions" +- :smile: "Choosing a license" +- :cry: "Code review" +- :cry: "Legal" ## Common Elements @@ -39,7 +39,7 @@ Every piece of content contains these elements: Each piece of content may also include: - [References](#references) -- [Credits](#credits) - +- [Credits](#credits) - ### Introductions @@ -92,23 +92,23 @@ Tactical content answers the question "How?". This is arguably the most common t Tactical content is structured as: -- **Title** - Tactical articles should begin with a gerund. For example, "Enforcing a code of conduct”. +- **Title** - Tactical articles should begin with a gerund. For example, "Enforcing a code of conduct". -- **Introduction** - The introduction should should explain what the user will specifically accomplish by applying these tactics, and can and probably should reference [conceptual content](#conceptual-content) to further explain why you would want to apply the tactics. For example, an article on “Enforcing a Code of Conduct” should reference the conceptual content “About codes of conduct”. +- **Introduction** - The introduction should should explain what the user will specifically accomplish by applying these tactics, and can and probably should reference [conceptual content](#conceptual-content) to further explain why you would want to apply the tactics. For example, an article on "Enforcing a Code of Conduct" should reference the conceptual content "About codes of conduct". -- **Tactical sections** - These sections explain each tactic involved in achieving the goal. They may be procedural steps, or just a list of individual tactics that should be considered. For example, an article on “Enforcing a code of conduct” might have a tactical section called “Responding to reports of abuse”. +- **Tactical sections** - These sections explain each tactic involved in achieving the goal. They may be procedural steps, or just a list of individual tactics that should be considered. For example, an article on "Enforcing a code of conduct" might have a tactical section called "Responding to reports of abuse". - **Summarizing conclusion** - Conclude by briefly reviewing how these tactics connect to the larger story and encouraging the user to find ways to apply them to their situation. - Links to **Related content** - Hopefully the user is excited about what they've just learned and wants to find out more. - + ### Frequently Asked Questions (FAQs) -FAQ articles aim to directly address common questions or misconceptions. These tend to be questions that have known but nuanced answers, such as “Is open source software secure?” or “How do I convince my boss to let me contribute to open source?”. +FAQ articles aim to directly address common questions or misconceptions. These tend to be questions that have known but nuanced answers, such as "Is open source software secure?" or "How do I convince my boss to let me contribute to open source?". FAQ content is structured as: -- **Title** should be in the form of a question. The question should be succinct and as close to the most widely asked form of the question, because not every person will ask a question in the same way. For example, “What is open source?”, or “How do I make money writing open source software?” +- **Title** should be in the form of a question. The question should be succinct and as close to the most widely asked form of the question, because not every person will ask a question in the same way. For example, "What is open source?", or "How do I make money writing open source software?" - **Body** should be as brief as possible - answering the question and linking off to more information where appropriate. Ask yourself if the question (the title) could be rephrased to create [conceptual](#conceptual-content) or [tactical](#tactical-content) content. @@ -124,5 +124,3 @@ Referential content is structured as: - **Title** - should begin with a noun describing the information that's being referenced, followed by how you'd use that thing. For example, "Countries that support SMS for two-factor authentication". It's always a good idea to link a referential article to a tactical or conceptual article, even if that's in the **Further reading** section at the end of the article. - - diff --git a/docs/personas.md b/docs/personas.md index 0792f2bb409..ba5890f3801 100644 --- a/docs/personas.md +++ b/docs/personas.md @@ -22,7 +22,7 @@ ### Frustrations/Pain Points -* Doesn’t know how to find an audience +* Doesn't know how to find an audience ## 2. Individual developer (multiple projects) @@ -42,7 +42,7 @@ ### Primary Goals -* Manage personal time so project demands don’t overwhelm him/her +* Manage personal time so project demands don't overwhelm him/her * Find other contributors or maintainers to help with the project @@ -74,7 +74,7 @@ ### Frustrations/Pain Points -* Managing a community is exhausting, especially when it’s volunteer work +* Managing a community is exhausting, especially when it's volunteer work ## 4. Corporate entity @@ -114,12 +114,12 @@ * Non-developers (individual, student, community, corporate) - * People who are open sourcing projects that don’t involve code (ex. books, documents, templates) + * People who are open sourcing projects that don't involve code (ex. books, documents, templates) * Can we use language that applies to both code- and non-code-centric projects? - * If we don’t tailor the handbook to them, will they feel isolated or ignored? Is there anything we’d miss about their experience? + * If we don't tailor the handbook to them, will they feel isolated or ignored? Is there anything we'd miss about their experience? * Student developer - * Likely more interested in learning how to contribute vs. how to start their own project. Set this aside for v1 (we’re primarily focusing on who produces open source projects) + * Likely more interested in learning how to contribute vs. how to start their own project. Set this aside for v1 (we're primarily focusing on who produces open source projects) diff --git a/getting-started/branding.md b/getting-started/branding.md index 888ec0bd861..ad76eccadb5 100644 --- a/getting-started/branding.md +++ b/getting-started/branding.md @@ -3,45 +3,45 @@ title: Branding next: getting-started/preparing.md --- -You’ve thought about who your users are, what they need from you, and what you might be able to offer them. Next, we’ll put that research into practice as we consider the brand of your project. +You've thought about who your users are, what they need from you, and what you might be able to offer them. Next, we'll put that research into practice as we consider the brand of your project. Branding may sound like a waste of time. After all there, are plenty of popular open source projects that have never thought about their brand at all. -But branding is more than a flashy logo or catchy project name. It’s about how you talk about your project and who you reach with your message. Here are a few things you’ll want to think about before you launch. +But branding is more than a flashy logo or catchy project name. It's about how you talk about your project and who you reach with your message. Here are a few things you'll want to think about before you launch. ## Choosing the right name Pick a name that is easy to remember and, ideally, gives some idea of what the project does. For example, [Sentry](https://github.com/getsentry/sentry) monitors apps for crash reporting, and [Thin](https://github.com/macournoyer/thin) is a fast and simple Ruby web server. -Consider clarity above all. Puns are fun, but remember that some jokes might not translate to other cultures or people with different experiences from you. For example, some of your users might be employees; you don’t want to make them uncomfortable when they have to explain your project’s name to coworkers! +Consider clarity above all. Puns are fun, but remember that some jokes might not translate to other cultures or people with different experiences from you. For example, some of your users might be employees; you don't want to make them uncomfortable when they have to explain your project's name to coworkers! ## Avoiding namespace conflicts -Make sure that your project’s name doesn’t infringe upon any trademarks. A company might ask you to take down your project later on, or even take legal action against you. It’s just not worth the risk. You can check for U.S. trademark conflicts [here](http://www.uspto.gov). +Make sure that your project's name doesn't infringe upon any trademarks. A company might ask you to take down your project later on, or even take legal action against you. It's just not worth the risk. You can check for U.S. trademark conflicts [here](http://www.uspto.gov). -You’ll also want to look for open source projects with a similar name, especially if you share the same language or ecosystem. If your name overlaps with a popular existing project, you will confuse your audience and make it less likely that anyone will use what you’ve created. You can check for similar project names [here](http://ivantomic.com/projects/ospnc/). +You'll also want to look for open source projects with a similar name, especially if you share the same language or ecosystem. If your name overlaps with a popular existing project, you will confuse your audience and make it less likely that anyone will use what you've created. You can check for similar project names [here](http://ivantomic.com/projects/ospnc/). -Consider whether you’ll want a website, Twitter handle, or other properties to represent your project. If so, make sure you can get the names you want. Ideally, reserve those names now so you have peace of mind. You can check for domain name availability [here](https://instantdomainsearch.com/). +Consider whether you'll want a website, Twitter handle, or other properties to represent your project. If so, make sure you can get the names you want. Ideally, reserve those names now so you have peace of mind. You can check for domain name availability [here](https://instantdomainsearch.com/). -Finally, it doesn’t hurt to do a quick Google search for your project name. Will people be able to easily find your project? Does something else appear in the search results that you wouldn’t want them to see? +Finally, it doesn't hurt to do a quick Google search for your project name. Will people be able to easily find your project? Does something else appear in the search results that you wouldn't want them to see? ## How you write (and code) affects your brand, too! -Throughout the life of your project, you’ll do a lot of writing: READMEs, tutorials, community documents, responding to issues, maybe even newsletters and mailing lists. Whether it’s official documentation or a casual email, how you write contributes to the brand of a project. Consider how you might come across to your audience and whether that is the tone you wish to convey. +Throughout the life of your project, you'll do a lot of writing: READMEs, tutorials, community documents, responding to issues, maybe even newsletters and mailing lists. Whether it's official documentation or a casual email, how you write contributes to the brand of a project. Consider how you might come across to your audience and whether that is the tone you wish to convey. @janl discovered that the way he spoke to others helped create a positive brand for [CouchDB](https://github.com/apache/couchdb): -> When I started out at CouchDB and we finally joined the ASF \[Apache Software Foundation\] and it was standard procedure to have a user@ mailing list for end-user support, I remembered my days in the #php channel and decided that that’s not the culture I want to have there. So for the first three or so years, I tried to be involved with every thread on the mailing list, and showing exemplary behaviour, being nice to people, taking their issues seriously and trying to be helpful overall. After a while, people stuck around not to only ask questions, but to help with the answering as well, and to my complete delight, they mimicked my style. \[...\] +> When I started out at CouchDB and we finally joined the ASF \[Apache Software Foundation\] and it was standard procedure to have a user@ mailing list for end-user support, I remembered my days in the #php channel and decided that that's not the culture I want to have there. So for the first three or so years, I tried to be involved with every thread on the mailing list, and showing exemplary behaviour, being nice to people, taking their issues seriously and trying to be helpful overall. After a while, people stuck around not to only ask questions, but to help with the answering as well, and to my complete delight, they mimicked my style. \[...\] > > Every time I join and read, I see the culture that I helped plant there seven years ago and it makes me very proud. [^1] [^1]: [Sustainable Open Source](http://writing.jan.io/2015/11/20/sustainable-open-source.html) by @janl -Beyond how you write words, your coding style may also become part of your project’s brand. For example, [Angular](https://github.com/johnpapa/angular-styleguide) and [jQuery](http://contribute.jquery.org/style-guide/js/) are two projects with rigorous coding styles and guidelines. +Beyond how you write words, your coding style may also become part of your project's brand. For example, [Angular](https://github.com/johnpapa/angular-styleguide) and [jQuery](http://contribute.jquery.org/style-guide/js/) are two projects with rigorous coding styles and guidelines. -It isn’t necessary to write a style guide for your project when you’re just starting out, and you may find that you enjoy incorporating different coding styles into your project anyway. But you should anticipate how your writing (and coding) style might attract (or not attract) different types of people. The earliest stages of your project are your opportunity to set the precedent you wish to see. +It isn't necessary to write a style guide for your project when you're just starting out, and you may find that you enjoy incorporating different coding styles into your project anyway. But you should anticipate how your writing (and coding) style might attract (or not attract) different types of people. The earliest stages of your project are your opportunity to set the precedent you wish to see. -We’re almost there! Next, we’ll walk you through a few components that every open source project should include when you launch. +We're almost there! Next, we'll walk you through a few components that every open source project should include when you launch. ## Further reading diff --git a/getting-started/index.md b/getting-started/index.md index 4ec3b7c9ae7..75778c5838b 100644 --- a/getting-started/index.md +++ b/getting-started/index.md @@ -5,9 +5,9 @@ next: getting-started/setting-expectations.md ## What does it mean to open source a project? -So you’re interested in making your project open source? Congratulations! 🎉 🙌 🌟 The world appreciates your contribution. +So you're interested in making your project open source? Congratulations! 🎉 🙌 🌟 The world appreciates your contribution. -Before we get into the details of running and managing an open source project, let’s talk about what open sourcing a project actually means. +Before we get into the details of running and managing an open source project, let's talk about what open sourcing a project actually means. ## Public projects on GitHub are not open source @@ -15,7 +15,7 @@ When you publish a project on GitHub, you have the option to make the repository Open source licenses grant permission to everyone to use, modify, and share licensed software for any purpose, subject to certain conditions, depending on the license. -Public repositories on GitHub [comply with GitHub’s Terms of Service](https://help.github.com/articles/open-source-licensing/), which gives other people the right to view and fork your repository. But if you want others to use, copy, modify, or contribute back to your project, you need to include an open source license. For example, someone cannot legally use your GitHub project in their code, even if it’s public, unless you explicitly give them the right to do so. (You can learn more about the legal side of open source [here](legal/).) +Public repositories on GitHub [comply with GitHub's Terms of Service](https://help.github.com/articles/open-source-licensing/), which gives other people the right to view and fork your repository. But if you want others to use, copy, modify, or contribute back to your project, you need to include an open source license. For example, someone cannot legally use your GitHub project in their code, even if it's public, unless you explicitly give them the right to do so. (You can learn more about the legal side of open source [here](legal/).) ## Open source is more than just a license @@ -23,14 +23,14 @@ Open source is defined by its legal protections and freedoms. In terms of cultur There are many reasons why a person or organization might want to open source a project. Some examples are: -* **Transparency:** Making your code visible means that anyone can inspect it for errors or inconsistencies. Transparency matters to governments like [Bulgaria](https://medium.com/@bozhobg/bulgaria-got-a-law-requiring-open-source-98bf626cf70a) or the [United States](https://sourcecode.cio.gov/), regulated industries like banking or healthcare, and security-related software infrastructure like [Let’s Encrypt](https://github.com/letsencrypt). +* **Transparency:** Making your code visible means that anyone can inspect it for errors or inconsistencies. Transparency matters to governments like [Bulgaria](https://medium.com/@bozhobg/bulgaria-got-a-law-requiring-open-source-98bf626cf70a) or the [United States](https://sourcecode.cio.gov/), regulated industries like banking or healthcare, and security-related software infrastructure like [Let's Encrypt](https://github.com/letsencrypt). * **Collaboration:** Projects that are open source can accept changes and updates from anybody. Collaboration matters to those who want to build their projects with a community, like [Hoodie](https://github.com/hoodiehq) and [Rust](https://github.com/rust-lang/rust). When people make improvements together, projects can thrive, because they draw from multiple skill sets, experiences, and levels of involvement. -* **Adoption and remixing:** Open source projects can be used by anyone for any purpose, whether it’s making a custom version of the original project, or using that project to build something else entirely. Code can reach more people when it is shared and reused, like [React](https://github.com/facebook/react) or [Sentry](https://github.com/getsentry/sentry). And new projects can grow out of older projects, like [WordPress and b2](https://github.com/WordPress/book/blob/master/Content/Part%201/2-b2-cafelog.md), or [Jenkins and Hudson](https://github.com/jenkinsci). +* **Adoption and remixing:** Open source projects can be used by anyone for any purpose, whether it's making a custom version of the original project, or using that project to build something else entirely. Code can reach more people when it is shared and reused, like [React](https://github.com/facebook/react) or [Sentry](https://github.com/getsentry/sentry). And new projects can grow out of older projects, like [WordPress and b2](https://github.com/WordPress/book/blob/master/Content/Part%201/2-b2-cafelog.md), or [Jenkins and Hudson](https://github.com/jenkinsci). -Remember: open source isn’t just for software! You can open source everything from data sets to websites to books. Check out [GitHub Explore](https://github.com/explore) for ideas on what else you can open source. +Remember: open source isn't just for software! You can open source everything from data sets to websites to books. Check out [GitHub Explore](https://github.com/explore) for ideas on what else you can open source. -When you open source a project, you open yourself to feedback and suggestions from other people who are engaged with your work. It might feel intimidating to open source a project for the first time, but remember that you’re not alone. +When you open source a project, you open yourself to feedback and suggestions from other people who are engaged with your work. It might feel intimidating to open source a project for the first time, but remember that you're not alone. -In the next section, we’ll help you figure out your goals around open sourcing your project. Understanding these goals beforehand will make it easier to manage your and others’ expectations later on. +In the next section, we'll help you figure out your goals around open sourcing your project. Understanding these goals beforehand will make it easier to manage your and others' expectations later on. diff --git a/getting-started/legal.md b/getting-started/legal.md index 4d5c51d9438..8cc35b824f6 100644 --- a/getting-started/legal.md +++ b/getting-started/legal.md @@ -2,9 +2,9 @@ title: The legal side of open source --- -Sharing your creative work with the world can be an exciting and rewarding experience. It can also mean a bunch of legal things you didn’t know you had to worry about. +Sharing your creative work with the world can be an exciting and rewarding experience. It can also mean a bunch of legal things you didn't know you had to worry about. -Thankfully, you don’t have to start from scratch. This section will make sure you’ve got all your legal needs covered. +Thankfully, you don't have to start from scratch. This section will make sure you've got all your legal needs covered. **(Do we need a legal disclaimer for this piece?)** @@ -13,8 +13,8 @@ Thankfully, you don’t have to start from scratch. This section will make sure 1. [Why do I need an open source license?](#why-do-i-need-an-open-source-license) 2. [Which open source license is appropriate for me?](#which-open-source-license-is-appropriate-for-me) 3. [Do I need a contributor agreement in addition to my open source license?](#do-i-need-a-contributor-agreement-in-addition-to-my-open-source-license) -4. [I’m a company open sourcing a project. What does my legal team need to know?](#im-a-company-open-sourcing-a-project-what-does-my-legal-team-need-to-know) -5. [I’m using others’ open source code. What does my legal team need to know?](#im-using-others-open-source-code-what-does-my-legal-team-need-to-know) +4. [I'm a company open sourcing a project. What does my legal team need to know?](#im-a-company-open-sourcing-a-project-what-does-my-legal-team-need-to-know) +5. [I'm using others' open source code. What does my legal team need to know?](#im-using-others-open-source-code-what-does-my-legal-team-need-to-know) ## Why do I need an open source license? @@ -28,13 +28,13 @@ Making your GitHub project public is not the same as licensing your project. Pub There are [over 70 approved licenses](https://opensource.org/licenses/alphabetical) that comply with the generally accepted definition of open source. Here is a breakdown of three of the most common licenses. -* **For individuals releasing an open source project with no deeper interests,** consider the [MIT License](http://choosealicense.com/licenses/mit/), which is simple and permissive. People can use your project for whatever they like, as long as they provide attribution back to you and don’t hold you liable for anything. +* **For individuals releasing an open source project with no deeper interests,** consider the [MIT License](http://choosealicense.com/licenses/mit/), which is simple and permissive. People can use your project for whatever they like, as long as they provide attribution back to you and don't hold you liable for anything. * **For companies releasing an open source project,** consider the [Apache License 2.0](http://choosealicense.com/licenses/apache-2.0/). The Apache 2.0 license is appropriate for project owners who are concerned about patents. It provides an express grant of patent rights from contributors. * **For those who care about keeping their code in the public domain,** consider the [GNU General Public License v3.0](http://choosealicense.com/licenses/gpl-3.0/), which is a copyleft license. That means anyone who distributes your code, or a derivative of your work, must make the source available under the same terms. It also provides an express grant of patent rights from contributors. -If your open source project isn’t software, consider a Creative Commons or other type of license that’s tailored for media. You can read more about choosing a non-software license [here](http://choosealicense.com/non-software/). +If your open source project isn't software, consider a Creative Commons or other type of license that's tailored for media. You can read more about choosing a non-software license [here](http://choosealicense.com/non-software/). -When you create a new project on GitHub, you are given the option to select a license. Including one of the above licenses will make your GitHub project open source. If you’d like to see other license options, check out [Choose a License](http://choosealicense.com) to find the right license for you. +When you create a new project on GitHub, you are given the option to select a license. Including one of the above licenses will make your GitHub project open source. If you'd like to see other license options, check out [Choose a License](http://choosealicense.com) to find the right license for you. ## Do I need a contributor agreement in addition to my open source license? @@ -42,35 +42,35 @@ Some open source projects, particularly when companies are involved, require a c Contributor agreements are used when the project owner wants to protect themselves, and their users, from future copyright claims from contributors. There are two major types of contributor agreements: -* [Contributor License Agreement (CLA)](https://www.apache.org/licenses/icla.txt): A CLA explicitly grants the project owner the right to distribute all contributions made by the contributor, either by assigning copyright or granting an irrevocable license. Some projects specify that CLAs only need to be signed for “non-trivial changes”: for example, fixing a significant bug rather than a small typo. -* [Developer Certificate of Origin (DCO)](http://developercertificate.org/): A DCO certifies that the contributor has the right to make their contribution and that they allow the project owner to use it in other distributions. Unlike a CLA, which must be explicitly signed, a DCO is required as a signature when the contribution is submitted, or is part of the project’s contribution policy. +* [Contributor License Agreement (CLA)](https://www.apache.org/licenses/icla.txt): A CLA explicitly grants the project owner the right to distribute all contributions made by the contributor, either by assigning copyright or granting an irrevocable license. Some projects specify that CLAs only need to be signed for "non-trivial changes": for example, fixing a significant bug rather than a small typo. +* [Developer Certificate of Origin (DCO)](http://developercertificate.org/): A DCO certifies that the contributor has the right to make their contribution and that they allow the project owner to use it in other distributions. Unlike a CLA, which must be explicitly signed, a DCO is required as a signature when the contribution is submitted, or is part of the project's contribution policy. -There are some concerns associated with CLAs in particular. CLAs can be perceived as not friendly to the project’s community. They can also create a lot of administrative work for the project owner. Finally, CLAs increase the barrier to community participation by adding more paperwork than some believe is necessary. +There are some concerns associated with CLAs in particular. CLAs can be perceived as not friendly to the project's community. They can also create a lot of administrative work for the project owner. Finally, CLAs increase the barrier to community participation by adding more paperwork than some believe is necessary. Many projects that use a CLA are concerned about patents. If you have patent concerns, consider adopting a license with patent protections instead, such as the [Apache License 2.0](http://choosealicense.com/licenses/apache-2.0/), in which contributors expressly grant patent rights. You can also consider using a DCO, which is less cumbersome than signing an agreement and provides similar benefits to a CLA. If your project is on GitHub, include the DCO in your CONTRIBUTING.md file, which is automatically referenced when someone submits a pull request. Or you can require that contributors include the DCO as a signature when they submit a pull request. -## I’m a company open sourcing a project. What does my legal team need to know? +## I'm a company open sourcing a project. What does my legal team need to know? If you are a company open sourcing a project, there are a few legal aspects you may want to consider. * **Existing Intellectual Property (IP):** Consider whether there is anything existing in the project that might fall under company IP, which you would not want to make available to the general public. If so, you could open source the rest of your project, but keep the IP private. * **Future Patents:** If you are concerned that there may be patents associated with your project later on, use an open source license that provides patent protections (such as the [Apache License 2.0](http://choosealicense.com/licenses/apache-2.0/)). -* **Employee contribution policies:** Consider developing a corporate policy that specifies how your employees contribute to open source projects, especially if you expect employees to maintain the project. A clear corporate policy will reduce confusion among your employees and encourage them to make open source contributions during work hours. A good example is Rackspace’s [Model IP and Open Source Contribution Policy](https://processmechanics.com/2015/07/23/a-model-ip-and-open-source-contribution-policy/). -* **Trademarks:** Double check that your project’s name does not conflict with any existing trademarks. If you use your own company trademarks in the project, check that it does not cause any conflicts. +* **Employee contribution policies:** Consider developing a corporate policy that specifies how your employees contribute to open source projects, especially if you expect employees to maintain the project. A clear corporate policy will reduce confusion among your employees and encourage them to make open source contributions during work hours. A good example is Rackspace's [Model IP and Open Source Contribution Policy](https://processmechanics.com/2015/07/23/a-model-ip-and-open-source-contribution-policy/). +* **Trademarks:** Double check that your project's name does not conflict with any existing trademarks. If you use your own company trademarks in the project, check that it does not cause any conflicts. These are starting points for conversation. Be sure to run any open source project by your legal team before proceeding! -## I’m using others’ open source code. What does my legal team need to know? +## I'm using others' open source code. What does my legal team need to know? -The implications of using others’ open source code in your software depends on that project’s license. (If the project does not have an open source license, don’t use it!) +The implications of using others' open source code in your software depends on that project's license. (If the project does not have an open source license, don't use it!) Some open source licenses, like the GNU GPLv3, require that any software using the code must license the source under the same terms. If you are a company using code with these restrictions, you will want to proceed carefully. Other open source licenses, like the MIT license, are very permissive. They may still require attribution. -If you use others’ open source code to create anything that could be considered company IP, you will want to read the terms of the license carefully to understand your patent rights. +If you use others' open source code to create anything that could be considered company IP, you will want to read the terms of the license carefully to understand your patent rights. To learn more about the implications of different open source licenses, [TLDRLegal](https://tldrlegal.com/) is a great resource. diff --git a/getting-started/preparing.md b/getting-started/preparing.md index a10b8b9bc30..0e1f247cd94 100644 --- a/getting-started/preparing.md +++ b/getting-started/preparing.md @@ -3,7 +3,7 @@ title: Preparing for launch next: marketing/index.md --- -You’re almost ready to launch your project! In this section, we’ll talk about what to include in an open source project before releasing it to the world. +You're almost ready to launch your project! In this section, we'll talk about what to include in an open source project before releasing it to the world. Every open source project should include the following: @@ -12,7 +12,7 @@ Every open source project should include the following: * Contributing guide * Code of conduct -As a maintainer, these components will help you communicate expectations, manage contributions, protect your legal rights, and make sure that you and your contributors have a positive experience. The more you can document for your readers up front, the less work you’ll have to do later on. +As a maintainer, these components will help you communicate expectations, manage contributions, protect your legal rights, and make sure that you and your contributors have a positive experience. The more you can document for your readers up front, the less work you'll have to do later on. ## Choosing a license @@ -20,7 +20,7 @@ An open source license guarantees that others can use, copy, modify and contribu Legal work is no fun. The good news is there are many licenses available that you can copy and paste into your repository. It will only take a minute to protect your hard work. -There are [over 70 approved licenses](https://opensource.org/licenses/alphabetical) that comply with the generally accepted definition of open source. Some licenses you’ll commonly hear about are: +There are [over 70 approved licenses](https://opensource.org/licenses/alphabetical) that comply with the generally accepted definition of open source. Some licenses you'll commonly hear about are: * [MIT License](http://choosealicense.com/licenses/mit/) * [Apache License 2.0](http://choosealicense.com/licenses/apache-2.0/) @@ -35,7 +35,7 @@ If you have other questions or concerns around the legal aspects of managing an ## Writing a README -Your project’s README file gives your reader context about the project. +Your project's README file gives your reader context about the project. The README should do more than explain how to use your project. It should also help your audience understand why the project is useful and what they can do with it. @@ -48,11 +48,11 @@ In your README, try to answer the following questions: You can also use your README to answer other questions, like how you handle contributions, what the goals of the project are, and information about licenses and attribution. -Sometimes, people avoid writing a README because they feel like the project is unfinished, or they don’t want contributions. These are all very good reasons to write one. +Sometimes, people avoid writing a README because they feel like the project is unfinished, or they don't want contributions. These are all very good reasons to write one. -As a maintainer, READMEs are an opportunity to clarify your goals in public. If you don’t want to accept contributions or your project is not yet ready for production, you should especially write this information down. That way, people understand your needs as soon as they arrive at your project. +As a maintainer, READMEs are an opportunity to clarify your goals in public. If you don't want to accept contributions or your project is not yet ready for production, you should especially write this information down. That way, people understand your needs as soon as they arrive at your project. -When you include a README file in the root directory, GitHub will automatically display it on your project repository’s homepage. It will be the first thing someone sees when they arrive. +When you include a README file in the root directory, GitHub will automatically display it on your project repository's homepage. It will be the first thing someone sees when they arrive. ## Setting your contributing guidelines @@ -60,7 +60,7 @@ A CONTRIBUTING file tells your audience how to participate in your project. For In addition to technical details, a CONTRIBUTING file is an opportunity to communicate your expectations for contributions. Remember that no two open source projects are alike. Write down rules that work best for you and your lifestyle. For example, you may want to convey that you are only accepting certain types of contributions, tell participants how long they should expect to hear a response from you, or explain how (or how not) to get in touch with you. -If you are a community project, you can use the CONTRIBUTING file to actively solicit the types of contributions you’re looking for. Using a warm, friendly tone and offering specific contribution suggestions (such as writing documentation, or making a website) can go a long way in making newcomers feel welcomed and excited to participate. +If you are a community project, you can use the CONTRIBUTING file to actively solicit the types of contributions you're looking for. Using a warm, friendly tone and offering specific contribution suggestions (such as writing documentation, or making a website) can go a long way in making newcomers feel welcomed and excited to participate. You should reference your CONTRIBUTING file in your README. In your README, give your audience a quick overview of how contributions work, then link to the CONTRIBUTING file for more information. @@ -68,21 +68,21 @@ If you place your CONTRIBUTING file in the root directory, GitHub will automatic ## Writing a code of conduct -Finally, a code of conduct helps set ground rules for communication among your project’s participants. The [Django Code of Conduct](https://www.djangoproject.com/conduct/) and the [Angular Code of Conduct](https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md) are two good examples. +Finally, a code of conduct helps set ground rules for communication among your project's participants. The [Django Code of Conduct](https://www.djangoproject.com/conduct/) and the [Angular Code of Conduct](https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md) are two good examples. -A code of conduct is a place to convey the values or philosophy that define your project. This is especially valuable if you’re a community or company launching an open source project. +A code of conduct is a place to convey the values or philosophy that define your project. This is especially valuable if you're a community or company launching an open source project. Codes of conduct help protect not just your participants, but yourself. As you maintain your project, you may find that unproductive attitudes from other participants can make you feel drained or unhappy about your work. A code of conduct empowers you to facilitate healthy, constructive community behavior. Being proactive about these expectations reduces the likelihood that you, or others, will become fatigued with your project later on. You can read more about enforcing codes of conduct [here](../../troubleshooting/conduct/). In addition to communicating your expectations, you should describe what happens if someone violates the code of conduct, and where someone can report such behavior. We recommend placing a CODE_OF_CONDUCT file in your root directory. -## What’s next? +## What's next? -Now that you have these four files in the root directory of your project, you’re ready to open source your project! Click "publish" and pat yourself on the back. Then continue on to the next section. We’ve got work to do. +Now that you have these four files in the root directory of your project, you're ready to open source your project! Click "publish" and pat yourself on the back. Then continue on to the next section. We've got work to do. -Launching your project is only the first step. If you’re hoping people will discover and use your project, you’ll want to make sure other people know about it. +Launching your project is only the first step. If you're hoping people will discover and use your project, you'll want to make sure other people know about it. -Sometimes, it will take a long time before people notice your open source project. Your project will likely go through multiple phases of activity and contributorship. That’s okay! Some of the most popular projects today took years to reach high levels of activity. The rest of this handbook is designed to help you manage your project every step of the way. +Sometimes, it will take a long time before people notice your open source project. Your project will likely go through multiple phases of activity and contributorship. That's okay! Some of the most popular projects today took years to reach high levels of activity. The rest of this handbook is designed to help you manage your project every step of the way. ## Further reading @@ -93,7 +93,7 @@ Sometimes, it will take a long time before people notice your open source projec * [Readme Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html) by @mojombo * [Awesome README](https://github.com/matiassingers/awesome-readme) * [18F Open Source Style Guide](https://pages.18f.gov/open-source-guide/making-readmes-readable/) - * [A Beginner’s Guide to Creating a README](https://changelog.com/a-beginners-guide-to-creating-a-readme/) by @beverlynelson + * [A Beginner's Guide to Creating a README](https://changelog.com/a-beginners-guide-to-creating-a-readme/) by @beverlynelson * [README.md template](https://gist.github.com/jxson/1784669) from @jxson * Contributing guides * [Contributing Guidelines](https://github.com/blog/1184-contributing-guidelines) by @vinbarnes diff --git a/getting-started/setting-expectations.md b/getting-started/setting-expectations.md index 1893afe7ef5..3a742e5492d 100644 --- a/getting-started/setting-expectations.md +++ b/getting-started/setting-expectations.md @@ -3,33 +3,33 @@ title: Setting expectations next: getting-started/branding.md --- -There are many reasons to open source a project. It’s a good idea to figure out yours before going public with your project. What you want to get out of the experience will guide how you manage your project and help you figure out where to say yes (and no!). +There are many reasons to open source a project. It's a good idea to figure out yours before going public with your project. What you want to get out of the experience will guide how you manage your project and help you figure out where to say yes (and no!). -In this section, we’ll help you think through a few important questions about the goals of your project. +In this section, we'll help you think through a few important questions about the goals of your project. ## Define your goals -Let’s start by defining your goals. Simply put: _why are you open sourcing this project?_ +Let's start by defining your goals. Simply put: _why are you open sourcing this project?_ There is no one right answer to this question. You may find that you have multiple goals for a single project, or that different projects have different goals. The most important thing is to be honest with yourself. Here are some examples of reasons why people open source their work: * An individual wants to show off his or her portfolio -* An individual or company wants others to use what they’ve created +* An individual or company wants others to use what they've created * A community wants to find collaborators to shape the project and help it grow * An individual wants to get feedback on their work * A company wants make their code transparent ## Figure out what you need from others -Once you’ve listed out your goals, ask yourself: _for each of these goals, what do I (or we) need from others?_ +Once you've listed out your goals, ask yourself: _for each of these goals, what do I (or we) need from others?_ -For example, if you are open sourcing a project to build your portfolio, you may not be actively looking for contributions, or you don’t have time to review them. In that case, you might clearly state in your README that you are not accepting contributions. For example, [Infinite-scroll](https://github.com/infinite-scroll/infinite-scroll) states this information at the top of its README. +For example, if you are open sourcing a project to build your portfolio, you may not be actively looking for contributions, or you don't have time to review them. In that case, you might clearly state in your README that you are not accepting contributions. For example, [Infinite-scroll](https://github.com/infinite-scroll/infinite-scroll) states this information at the top of its README. -On the other hand, if you are building a community project, you may be very actively looking for contributors. In this case, you might want to be more detailed about the types of contributions you’re looking for and explicitly give your readers permission to modify and shape the project. For example, [Sinatra](https://github.com/sinatra/sinatra/blob/master/CONTRIBUTING.md) lists all the types of contributions they'd love to have. +On the other hand, if you are building a community project, you may be very actively looking for contributors. In this case, you might want to be more detailed about the types of contributions you're looking for and explicitly give your readers permission to modify and shape the project. For example, [Sinatra](https://github.com/sinatra/sinatra/blob/master/CONTRIBUTING.md) lists all the types of contributions they'd love to have. -If you’re hoping to get feedback on something you’ve created, consider asking for the type of feedback you’re looking for, whether it’s general code review or help with a specific bug. For example, [Geocoder](https://github.com/alexreisner/geocoder#known-issue) calls out a known issue in its README. +If you're hoping to get feedback on something you've created, consider asking for the type of feedback you're looking for, whether it's general code review or help with a specific bug. For example, [Geocoder](https://github.com/alexreisner/geocoder#known-issue) calls out a known issue in its README. ## Figure out what others need from you @@ -39,19 +39,19 @@ Try to anticipate these needs beforehand so you can add them to your project fro Remember that as your project grows, your users may need more than just code from you. Responding to issues, reviewing code, and evangelizing your project are all important tasks in an open source project. While the amount of time you spend on non-coding tasks will depend on the size and scope of your project, you should be prepared as a maintainer to address them yourself or find someone to help you. -Here are some questions to ask yourself early on. If you don’t know the answers, consider how you might be able to figure them out (for example, polling others online or reading through forums where your users might congregate). +Here are some questions to ask yourself early on. If you don't know the answers, consider how you might be able to figure them out (for example, polling others online or reading through forums where your users might congregate). -* Does the project’s name resonate with my audience? Will they remember it or think it is clever? +* Does the project's name resonate with my audience? Will they remember it or think it is clever? * What are the skills and background of my audience? Do they need to know anything special about how to use my project? * Where might my users feel frustrated? Can I (or we) make it easier somehow? * Will my users need extra help or support anywhere? * How does this project compare to other projects that my audience might be familiar with? -## Save your answers, you’ll need them! +## Save your answers, you'll need them! Congratulations, you just did your first round of user research for your project! If you wrote down the answers to the above questions, save them for later. You can reference your goals and expectations as you develop your project. -We’ll also use these answers in the next section, as you consider the brand of your project. +We'll also use these answers in the next section, as you consider the brand of your project. ## Further reading diff --git a/index.md b/index.md index c76aba03428..da88ff5619d 100644 --- a/index.md +++ b/index.md @@ -5,6 +5,6 @@ next: getting-started/index.md Welcome to the Open Source Handbook! We created this handbook to help creators like you successfully release and grow your projects. -We wrote this handbook based on what we’ve learned from watching millions of open source projects on GitHub’s platform. Whether you’re an individual, a company, or a community, you’ll find plenty of real stories and experiences in this handbook to guide you. +We wrote this handbook based on what we've learned from watching millions of open source projects on GitHub's platform. Whether you're an individual, a company, or a community, you'll find plenty of real stories and experiences in this handbook to guide you. -Special thanks to **(list names of people here)** for their valuable input in the initial release of this handbook. If you’d like to contribute, head on over to to get started! +Special thanks to **(list names of people here)** for their valuable input in the initial release of this handbook. If you'd like to contribute, head on over to to get started! diff --git a/marketing/building-community.md b/marketing/building-community.md index 4ac2e967317..85977a1b4da 100644 --- a/marketing/building-community.md +++ b/marketing/building-community.md @@ -3,7 +3,7 @@ title: Building a community next: marketing/measuring.md --- -You’ve launched your project, you’re spreading the word, and people are checking out your project. Awesome! Now, how do you get them to stick around? In this section, we’ll discuss ways to encourage people to use, contribute to, and evangelize your project. +You've launched your project, you're spreading the word, and people are checking out your project. Awesome! Now, how do you get them to stick around? In this section, we'll discuss ways to encourage people to use, contribute to, and evangelize your project. ## Give your community a place to congregate @@ -11,21 +11,21 @@ There are two reasons to give your community a place to congregate. The first reason is for them. People with common interests will inevitably want a place to talk about it. And when communication is public and accessible, anybody can read past archives to get up to speed and new people will feel more comfortable participating. Helping people forge connections with each other will build a stronger and more resilient community. -The second reason is for you. If you don’t give people a public place to talk about your project, they will likely contact you directly. In the beginning, it may seem easy enough to respond to private messages "just this once". But over time, especially as your project becomes popular, you will become exhausted. Resist the temptation to communicate with people about your project in private. Instead, direct them to a designated public channel. +The second reason is for you. If you don't give people a public place to talk about your project, they will likely contact you directly. In the beginning, it may seem easy enough to respond to private messages "just this once". But over time, especially as your project becomes popular, you will become exhausted. Resist the temptation to communicate with people about your project in private. Instead, direct them to a designated public channel. If your project is on GitHub, public communication can be as simple as directing people to use GitHub Issues instead of emailing you directly. You could also set up a mailing list (such as [Google Groups](https://groups.google.com/forum/#!overview)) or create a Twitter account, Slack, or IRC channel for people to talk about your project. Or try all of the above! ## Make people feel welcome -A welcoming community is an investment into your project’s future and reputation. When someone new lands on your project, make sure to thank them for their interest! Show them around and help them get started. Point them to resources, like onboarding materials or past mailing list threads, that you think might be helpful. It only takes one negative experience to make someone not want to come back. +A welcoming community is an investment into your project's future and reputation. When someone new lands on your project, make sure to thank them for their interest! Show them around and help them get started. Point them to resources, like onboarding materials or past mailing list threads, that you think might be helpful. It only takes one negative experience to make someone not want to come back. -You don’t have to overdo it or feel like you’re putting others’ needs in front of your own. Be honest about your project’s needs, but do so with an assertive attitude. You can stand up for yourself without being rude, flippant, or unhelpful. +You don't have to overdo it or feel like you're putting others' needs in front of your own. Be honest about your project's needs, but do so with an assertive attitude. You can stand up for yourself without being rude, flippant, or unhelpful. ## Document everything -When you start an open source project, it may feel natural to keep your ideas and workflows private. But open source projects thrive when you document your process in public. That way, more people can participate at every step of the way. Not only will they know _what_ to contribute, but they’ll also know _how_. You might get help on something you didn’t even know you needed. +When you start an open source project, it may feel natural to keep your ideas and workflows private. But open source projects thrive when you document your process in public. That way, more people can participate at every step of the way. Not only will they know _what_ to contribute, but they'll also know _how_. You might get help on something you didn't even know you needed. -Documenting your open source project means more than just technical documentation. Be transparent about your project’s roadmap, your timeline for completing new features, the types of contributions you’re looking for, how contributions are reviewed and accepted, or why you made certain decisions. Any time you feel the urge to write something down about your project, ask yourself whether you can make it public. The feedback you’ll get from this level of transparency may surprise you. +Documenting your open source project means more than just technical documentation. Be transparent about your project's roadmap, your timeline for completing new features, the types of contributions you're looking for, how contributions are reviewed and accepted, or why you made certain decisions. Any time you feel the urge to write something down about your project, ask yourself whether you can make it public. The feedback you'll get from this level of transparency may surprise you. ## Be responsive @@ -39,7 +39,7 @@ Remember that conversations about your project could also be happening in other ## Make it easy for people to use and contribute -One way to think about your project’s community is what @MikeMcQuaid calls the contributor funnel. [^2] At the top of the funnel is anybody who could potentially use your project. At the bottom of the funnel are people like you who maintain the project. +One way to think about your project's community is what @MikeMcQuaid calls the contributor funnel. [^2] At the top of the funnel is anybody who could potentially use your project. At the bottom of the funnel are people like you who maintain the project. [^2]: [The Open Source Contributor Funnel](https://speakerdeck.com/mikemcquaid/the-open-source-contributor-funnel) by @MikeMcQuaid @@ -47,9 +47,9 @@ As you build your community, consider how someone at the top of the funnel (a po Start by making it easy for someone to use your project. Tutorials, clear code examples, good documentation, and a friendly README will make it easier for anyone who lands on your project to understand its value and get started. -For casual or first-time contributors, be open-minded about the types of contributions you’ll accept. Many casual contributors start with a small fix. A new contributor might write a tutorial or improve your project’s documentation, because newer users notice things that more experienced users might not. Let people help how they want to help. If there’s a contribution you disagree with, thank them for their idea and explain why it doesn’t fit into the scope of the project. If there are certain types of contributions that you won’t accept, explain so in your CONTRIBUTING.md file. +For casual or first-time contributors, be open-minded about the types of contributions you'll accept. Many casual contributors start with a small fix. A new contributor might write a tutorial or improve your project's documentation, because newer users notice things that more experienced users might not. Let people help how they want to help. If there's a contribution you disagree with, thank them for their idea and explain why it doesn't fit into the scope of the project. If there are certain types of contributions that you won't accept, explain so in your CONTRIBUTING.md file. -You’re doing great so far! Now that you’re promoting your project and growing a community, you’re probably wondering whether you’re doing it right. In the next section, we’ll talk about metrics to measure your project’s success and how to track them. +You're doing great so far! Now that you're promoting your project and growing a community, you're probably wondering whether you're doing it right. In the next section, we'll talk about metrics to measure your project's success and how to track them. ## Further reading diff --git a/marketing/index.md b/marketing/index.md index 7acc76cbde0..b316c929494 100644 --- a/marketing/index.md +++ b/marketing/index.md @@ -3,6 +3,6 @@ title: Marketing your project next: marketing/spreading-word.md --- -This section of the handbook will help you spread the word about your project and grow your initial community of users and contributors. If you’re looking for feedback on your project, or want people to use and share your work, this part is for you. +This section of the handbook will help you spread the word about your project and grow your initial community of users and contributors. If you're looking for feedback on your project, or want people to use and share your work, this part is for you. -Remember, reaching your audience takes time. It may take months or years for you to grow a community around your project. Don’t give up! It’s all part of the process. +Remember, reaching your audience takes time. It may take months or years for you to grow a community around your project. Don't give up! It's all part of the process. diff --git a/marketing/measuring.md b/marketing/measuring.md index b12f86977bf..31b6e0c8c54 100644 --- a/marketing/measuring.md +++ b/marketing/measuring.md @@ -3,13 +3,13 @@ title: Measuring Success next: sustaining/index.md --- -Your project is starting to grow. 🌱 Well, you think it’s growing. Is it growing? In this section, we’ll talk about how to measure and track the success of your open source project. +Your project is starting to grow. 🌱 Well, you think it's growing. Is it growing? In this section, we'll talk about how to measure and track the success of your open source project. ## Discoverability -Before anybody can use or contribute back to your project, they first need to know it exists. The first question you’ll want to ask yourself, then, is: _are people finding my project?_ +Before anybody can use or contribute back to your project, they first need to know it exists. The first question you'll want to ask yourself, then, is: _are people finding my project?_ -If your project is hosted on GitHub, you can view how many people land on your project and where they come from. From your project’s page, click "Graphs", then “Traffic”. On this page, you can see: +If your project is hosted on GitHub, you can view how many people land on your project and where they come from. From your project's page, click "Graphs", then "Traffic". On this page, you can see: * **Total pageviews:** Tells you how many times your project was viewed @@ -19,33 +19,33 @@ If your project is hosted on GitHub, you can view how many people land on your p * **Popular content:** Tells you where visitors go on your project, broken down by pageviews and unique visitors. -[GitHub stars](https://github.com/blog/1204-notifications-stars) can also help provide a baseline measure of popularity. While GitHub stars don’t necessarily correlate to downloads and usage, they can tell you how many people are taking notice of your work. +[GitHub stars](https://github.com/blog/1204-notifications-stars) can also help provide a baseline measure of popularity. While GitHub stars don't necessarily correlate to downloads and usage, they can tell you how many people are taking notice of your work. -You may also want to track discoverability in specific places: for example, Google PageRank, referral traffic from your project’s website, or referrals from other open source projects or websites. +You may also want to track discoverability in specific places: for example, Google PageRank, referral traffic from your project's website, or referrals from other open source projects or websites. ## Usage -People are finding your project on this wild and crazy thing we call the Internet. Ideally, when they see your project, they’ll feel compelled to do something. The second question you’ll want to ask is: _are people using my project?_ +People are finding your project on this wild and crazy thing we call the Internet. Ideally, when they see your project, they'll feel compelled to do something. The second question you'll want to ask is: _are people using my project?_ -If you use a package manager, such as npm or RubyGems.org, to distribute your project, you may be able to track your project’s downloads. Each package manager may use a slightly different definition of "download", and downloads do not not necessarily correlate to installs or use, but it provides some baseline for comparison. +If you use a package manager, such as npm or RubyGems.org, to distribute your project, you may be able to track your project's downloads. Each package manager may use a slightly different definition of "download", and downloads do not not necessarily correlate to installs or use, but it provides some baseline for comparison. If your project is on GitHub, navigate again to the "Traffic" page. You can use the [clone graph](https://github.com/blog/1873-clone-graphs) to see how many times your project has been cloned on a given day, broken down by total clones and unique cloners. -If usage is low compared to the number of people discovering your project, there are two issues to consider: 1) that your project isn’t successfully converting your audience, or 2) that you’re attracting the wrong audience. For example, if your project lands on the front page of Hacker News, you’ll probably see a traffic spike but a lower conversion rate because you’re reaching everyone on Hacker News, not just your target audience. Try to figure out where your audience is coming from and ask others for feedback on your project page to figure out which of these two issues you’re facing. +If usage is low compared to the number of people discovering your project, there are two issues to consider: 1) that your project isn't successfully converting your audience, or 2) that you're attracting the wrong audience. For example, if your project lands on the front page of Hacker News, you'll probably see a traffic spike but a lower conversion rate because you're reaching everyone on Hacker News, not just your target audience. Try to figure out where your audience is coming from and ask others for feedback on your project page to figure out which of these two issues you're facing. ## Retention -People are finding your project and they’re using it. The last question you’ll want to ask yourself is: _are people contributing back to my project?_ +People are finding your project and they're using it. The last question you'll want to ask yourself is: _are people contributing back to my project?_ -This is a big one. Without other people pitching in, you risk putting yourself into an unhealthy situation where your project is popular (many people use it) but not supported (not enough maintainer time to meet demand). It’s never too early to start thinking about contributors! +This is a big one. Without other people pitching in, you risk putting yourself into an unhealthy situation where your project is popular (many people use it) but not supported (not enough maintainer time to meet demand). It's never too early to start thinking about contributors! Here are a few types of contributor metrics you may want to regularly keep track of: -* **Total contributor count and number of commits per contributor:** Tells you how many contributors you have, and who’s more or less active. You can view this under "Graphs" -> “Contributors” +* **Total contributor count and number of commits per contributor:** Tells you how many contributors you have, and who's more or less active. You can view this under "Graphs" -> "Contributors" -* **Casual contributors:** This is defined as contributors with only low number of commits. Whether that’s one commit, less than five commits, or something else is up to you. +* **Casual contributors:** This is defined as contributors with only low number of commits. Whether that's one commit, less than five commits, or something else is up to you. -* **First time vs. repeat contributors:** Helps you track whether you’re getting new contributors in. Without new contributors, your project’s community can become stagnant. +* **First time vs. repeat contributors:** Helps you track whether you're getting new contributors in. Without new contributors, your project's community can become stagnant. * **Number of open issues and open pull requests:** If these numbers get too high, you might need help with issue triaging and code reviews. diff --git a/marketing/spreading-word.md b/marketing/spreading-word.md index d8051d28c44..ed8d1644668 100644 --- a/marketing/spreading-word.md +++ b/marketing/spreading-word.md @@ -3,21 +3,21 @@ title: Spreading the word next: marketing/building-community.md --- -You’ve just published your project–what’s next? It’s time to tell everybody about your hard work! +You've just published your project–what's next? It's time to tell everybody about your hard work! -In this section, we’ll go through some of the most effective ways that people promote their open source projects. But before we do, let’s start with a few tips that will help you make the most of your outreach. +In this section, we'll go through some of the most effective ways that people promote their open source projects. But before we do, let's start with a few tips that will help you make the most of your outreach. ## Be able to convey who you are (and why it matters) Before you start the hard work of promoting your project, you should be able to explain why your project is different or interesting. Why should someone get excited about your work? Answering this question for yourself will make it easier to convince others. -The best way to invite people to share and contribute to your project is to share and contribute to their projects. There is no better way to convince people of your project's value than to invest time into your community. Helping newcomers, sharing resources, and making thoughtful contributions to others' work will earn you a positive reputation. Then, when you launch your own project, people will have context for your work and be more likely to pay attention and share what you’re doing. +The best way to invite people to share and contribute to your project is to share and contribute to their projects. There is no better way to convince people of your project's value than to invest time into your community. Helping newcomers, sharing resources, and making thoughtful contributions to others' work will earn you a positive reputation. Then, when you launch your own project, people will have context for your work and be more likely to pay attention and share what you're doing. -There is no magical formula to building an audience and reputation. Gaining the trust and respect of others takes time—it’s never too early or too late to start. +There is no magical formula to building an audience and reputation. Gaining the trust and respect of others takes time—it's never too early or too late to start. ## Help people find you and follow your work -You can help people find and remember you by pointing them to your project’s namespace—a website, Twitter handle, or IRC channel, for example. +You can help people find and remember you by pointing them to your project's namespace—a website, Twitter handle, or IRC channel, for example. Consider creating a website for your project. @adrianholovaty called a well-designed site "by far the best thing we did with Django in the early days"[^1]. [Yeoman](http://yeoman.io/), [Vagrant](https://www.vagrantup.com/), and [Middleman](https://middlemanapp.com/) are a few more examples of excellent, comprehensive websites. @@ -25,9 +25,9 @@ Consider creating a website for your project. @adrianholovaty called a well-desi A website, along with clear documentation and tutorials, makes your project seem friendly and easy to navigate. It also suggests that your project is active and supported, which will make your audience feel more comfortable using it. Adding tutorials and examples gives people ideas for ways they can use your project. -A Twitter handle or IRC channel is like a calling card for your project. It gives people a place to convene around your project, which will help grow your community. If you don’t wish to set up these channels for your project yet, promote your own Twitter or GitHub handle in everything you do. For example, make sure it is included in your bio or slides if you speak at a meetup or event. That way, people know who you are and how to reach you or follow your work. +A Twitter handle or IRC channel is like a calling card for your project. It gives people a place to convene around your project, which will help grow your community. If you don't wish to set up these channels for your project yet, promote your own Twitter or GitHub handle in everything you do. For example, make sure it is included in your bio or slides if you speak at a meetup or event. That way, people know who you are and how to reach you or follow your work. -Now that you have a marketing message for your project, and clear ways for people to reach you, let’s get out there and talk to your audience! +Now that you have a marketing message for your project, and clear ways for people to reach you, let's get out there and talk to your audience! ## Go where your audience is (online) @@ -39,17 +39,17 @@ Consider introducing yourself and your work to related open source projects and ## Go where your audience is (offline) -Look for meetups and conferences that are relevant to your work. Offline outreach is a great way to reach an engaged audience and build deeper human connections, especially if you are interested in reaching developers. @mitchellh attributes [Vagrant](https://github.com/mitchellh/vagrant)’s growth and popularity to the talks he gave about the project. [^2] +Look for meetups and conferences that are relevant to your work. Offline outreach is a great way to reach an engaged audience and build deeper human connections, especially if you are interested in reaching developers. @mitchellh attributes [Vagrant](https://github.com/mitchellh/vagrant)'s growth and popularity to the talks he gave about the project. [^2] [^2]: [Notes from @mitchellh's 2016 CodeConf talk](https://github.com/swinton/codeconf/blob/master/the-hashicorp-formula-to-open-source.md) -If you’re new to public speaking, start by finding a local meetup that’s related to the language or ecosystem of your project. If you’ve never spoken at an event before, it’s perfectly normal to feel nervous! Remember that your audience is there because they genuinely want to hear about your work. As you design your talk, remember to focus on what your audience will find interesting and get value out of. Keep your language friendly and approachable. Smile, breathe, and have fun. +If you're new to public speaking, start by finding a local meetup that's related to the language or ecosystem of your project. If you've never spoken at an event before, it's perfectly normal to feel nervous! Remember that your audience is there because they genuinely want to hear about your work. As you design your talk, remember to focus on what your audience will find interesting and get value out of. Keep your language friendly and approachable. Smile, breathe, and have fun. -When you feel ready, consider speaking at a conference to promote your project. Conferences can help you reach more people, sometimes from all over the world. Look for conferences that are specific to your language or ecosystem. Before you submit your talk, research the conference and its attendees beforehand to understand what they want to learn about, which will help you tailor your talk and increase your chances of getting accepted. You can often get a sense of a conference’s audience by looking at its speakers. +When you feel ready, consider speaking at a conference to promote your project. Conferences can help you reach more people, sometimes from all over the world. Look for conferences that are specific to your language or ecosystem. Before you submit your talk, research the conference and its attendees beforehand to understand what they want to learn about, which will help you tailor your talk and increase your chances of getting accepted. You can often get a sense of a conference's audience by looking at its speakers. Spreading the word is an important step in growing the popularity of your project. It can be scary to share your creativity with the world, so give yourself a high five for making it this far! 👌 💯 🙌 -In the next section, we’ll talk about how to retain those early enthusiasts and grow an engaged community around your project. +In the next section, we'll talk about how to retain those early enthusiasts and grow an engaged community around your project. ## Further reading diff --git a/sustaining/best-practices.md b/sustaining/best-practices.md index 55749f8fec4..d49525d2f85 100644 --- a/sustaining/best-practices.md +++ b/sustaining/best-practices.md @@ -5,57 +5,57 @@ next: sustaining/healthy-communities.md In this handbook, we spend plenty of time talking about how to make other people happy. But first and foremost, make yourself happy. Your happiness and health are the most important requirements of open source work. Without them, nothing else matters. -As you’ve probably noticed, a major part of maintaining an active open source project is managing other people. While that can be a lot less fun than coding or writing, there are things you can do to make your life easier. +As you've probably noticed, a major part of maintaining an active open source project is managing other people. While that can be a lot less fun than coding or writing, there are things you can do to make your life easier. -In this section, we’ll talk about how to set up your projects in a way that helps you maintain your sanity. +In this section, we'll talk about how to set up your projects in a way that helps you maintain your sanity. ## Know yourself and your needs -Remember way back, before you launched your project, [when you wrote down](../../getting-started/setting-expectations) your expectations? It’s time to revisit that document now. Remind yourself why you’re doing this work and what you want to get out of open sourcing your project. Has anything changed? +Remember way back, before you launched your project, [when you wrote down](../../getting-started/setting-expectations) your expectations? It's time to revisit that document now. Remind yourself why you're doing this work and what you want to get out of open sourcing your project. Has anything changed? Be honest with yourself about how much time you have to spend on your project. This is not the same as how much time you think the project requires, or how much time you think others want you to spend on your project. Write down your time constraints, and make it public so others understand your priorities, too. -Write down your project’s vision and, where possible, make that vision transparent to others. Your vision is your North Star, guiding you when you feel overwhelmed by others’ requests, and helping you reset your priorities. Add it to your README. If there are related artifacts that you think could help, like a project roadmap, make those public as well. +Write down your project's vision and, where possible, make that vision transparent to others. Your vision is your North Star, guiding you when you feel overwhelmed by others' requests, and helping you reset your priorities. Add it to your README. If there are related artifacts that you think could help, like a project roadmap, make those public as well. -@lord discovered that having a project vision helped him figure out which requests he should spend time on. As a new maintainer, he regretted not sticking to his project’s scope when he got his first feature request for [Slate](https://github.com/lord/slate): +@lord discovered that having a project vision helped him figure out which requests he should spend time on. As a new maintainer, he regretted not sticking to his project's scope when he got his first feature request for [Slate](https://github.com/lord/slate): -> I fumbled it. I didn’t put in the effort to come up with a complete solution. Instead of an half-assed solution, I wish I had said “I don’t have time for this right now, but I’ll add it to the long term nice-to-have list."[^1] +> I fumbled it. I didn't put in the effort to come up with a complete solution. Instead of an half-assed solution, I wish I had said "I don't have time for this right now, but I'll add it to the long term nice-to-have list."[^1] [^1]: [Tips for New Open Source Maintainers](https://lord.io/blog/2014/oss-tips/) by @lord -These types of exercises may seem trivial, but the more you know yourself and your limits (not just abilities!), the easier it is to say no to things that don’t fit into your scope. +These types of exercises may seem trivial, but the more you know yourself and your limits (not just abilities!), the easier it is to say no to things that don't fit into your scope. ## Write down your rules -Rules can be nerve-wracking to write down. Sometimes you might feel like you’re policing other people’s behavior or killing all the fun. +Rules can be nerve-wracking to write down. Sometimes you might feel like you're policing other people's behavior or killing all the fun. -Done right, however, good rules empower maintainers. Rules are your chance to explain how you want to manage your project. They help prevent you from getting dragged into doing things you don’t want to do. And the more guidelines you write down (and enforce fairly), the more people can understand your perspective without you having to explain yourself. +Done right, however, good rules empower maintainers. Rules are your chance to explain how you want to manage your project. They help prevent you from getting dragged into doing things you don't want to do. And the more guidelines you write down (and enforce fairly), the more people can understand your perspective without you having to explain yourself. Some examples of rules you may want to write down: * How a contribution is reviewed and accepted -* The types of contributions you will or won’t accept +* The types of contributions you will or won't accept -* How long someone should expect for you to respond, and when it’s appropriate to follow up (ex. "You can expect a response from maintainers within 7 days. If you haven’t heard anything by then, feel free to ping the same thread.") +* How long someone should expect for you to respond, and when it's appropriate to follow up (ex. "You can expect a response from maintainers within 7 days. If you haven't heard anything by then, feel free to ping the same thread.") -* How people can (and can’t) contact you +* How people can (and can't) contact you -* How much time you spend on the project (for example: "I only work on this project on weekends" or “I spend 10 percent of my employer’s time on this project, usually Wednesdays through Fridays”) +* How much time you spend on the project (for example: "I only work on this project on weekends" or "I spend 10 percent of my employer's time on this project, usually Wednesdays through Fridays") ## Learn to say no -The first rule of open source, according to @shykes: _"No is temporary, yes is forever."_[^2] If you plan on maintaining open source projects for a long time, it’s never too early to practice saying no. +The first rule of open source, according to @shykes: _"No is temporary, yes is forever."_[^2] If you plan on maintaining open source projects for a long time, it's never too early to practice saying no. [^2]: [tweet from @solomonstre](https://twitter.com/solomonstre/status/715277134978113536) -Saying no applies to many situations you’ll come across as a maintainer. You can say no to feature requests that don’t fit the scope of your project. You can say no, or refuse to engage, when someone derails a conversation on a mailing list. You can say no to doing work for others that you don’t find important. +Saying no applies to many situations you'll come across as a maintainer. You can say no to feature requests that don't fit the scope of your project. You can say no, or refuse to engage, when someone derails a conversation on a mailing list. You can say no to doing work for others that you don't find important. -One of the most important places you’ll practice saying no is on your your issue and pull request queue. If someone suggests an idea that you know you won’t accept, don’t leave it open because you feel guilty or want to be nice. Be kind, but firm. Thank them for their contribution and explain why it doesn’t fit into the scope of the project. Then close the request. +One of the most important places you'll practice saying no is on your your issue and pull request queue. If someone suggests an idea that you know you won't accept, don't leave it open because you feel guilty or want to be nice. Be kind, but firm. Thank them for their contribution and explain why it doesn't fit into the scope of the project. Then close the request. -If you notice repeated requests for things you don’t want to accept, consider adding them into your contribution policy, so you don’t have to keep repeating yourself. +If you notice repeated requests for things you don't want to accept, consider adding them into your contribution policy, so you don't have to keep repeating yourself. -If the thought of saying no terrifies you, you’re not alone. As @jfrazelle put it: _"I’ve talked to maintainers from several different open source projects, Mesos, Kubernetes, Chromium, and they all agree one of the hardest parts of being a maintainer is saying “No" to patches you don’t want.”_ [^3] But the more often you practice saying no, the easier it becomes. Promise. +If the thought of saying no terrifies you, you're not alone. As @jfrazelle put it: _"I've talked to maintainers from several different open source projects, Mesos, Kubernetes, Chromium, and they all agree one of the hardest parts of being a maintainer is saying "No" to patches you don't want."_ [^3] But the more often you practice saying no, the easier it becomes. Promise. [^3]: [The Art of Closing](https://blog.jessfraz.com/post/the-art-of-closing/) by @jfrazelle @@ -63,15 +63,15 @@ If the thought of saying no terrifies you, you’re not alone. As @jfrazelle put Wherever you can, keep communication about your project public. If somebody tries to contact you privately to discuss a feature request or support need, politely direct them to a public communication channel, such as a mailing list or issue tracker. -It’s tempting to respond to private communication, especially early in the life of a project. Resist the temptation. Keeping communication public means less work for you personally. It also opens up opportunities for other people to learn and participate. +It's tempting to respond to private communication, especially early in the life of a project. Resist the temptation. Keeping communication public means less work for you personally. It also opens up opportunities for other people to learn and participate. -Notable exceptions to this practice are: 1) security issues and 2) sensitive code of conduct violations. You should always have a way for people to report these types of issues privately. If you don’t want to use your personal communication channels, set up a separate email address for this purpose. +Notable exceptions to this practice are: 1) security issues and 2) sensitive code of conduct violations. You should always have a way for people to report these types of issues privately. If you don't want to use your personal communication channels, set up a separate email address for this purpose. ## Automate your work The good news about maintaining a popular open source project is that other maintainers have probably struggled with similar issues. There are a variety of tools available to help automate your work. For example: -* [Greenkeeper](https://github.com/greenkeeperio/greenkeeper) monitors your project’s dependencies +* [Greenkeeper](https://github.com/greenkeeperio/greenkeeper) monitors your project's dependencies * [Coveralls](https://coveralls.io/) checks for test coverage @@ -81,13 +81,13 @@ The good news about maintaining a popular open source project is that other main * [PullApprove](https://about.pullapprove.com/) helps you manage pull requests -One of the most important ways you can automate your project is by adding tests. Tests help contributors feel confident that they won’t break anything. They also make it easier for you to review and accept contributions quickly. The more responsive you are, the more engaged your community can be. If you add tests to your project, make sure to explain how they work in your CONTRIBUTING.md file. +One of the most important ways you can automate your project is by adding tests. Tests help contributors feel confident that they won't break anything. They also make it easier for you to review and accept contributions quickly. The more responsive you are, the more engaged your community can be. If you add tests to your project, make sure to explain how they work in your CONTRIBUTING.md file. For bug reports and other common contributions, GitHub has [Issue Templates and Pull Request Templates](https://github.com/blog/2111-issue-and-pull-request-templates), which you can create to streamline the communication you receive. -If you want to get a little more advanced, style guides and linters can help standardize project contributions and make them easier to review and accept. However, if your standards are too complicated, they can increase the barriers to contribution, so proceed carefully here and make sure you’re only adding just enough rules to make everyone’s lives easier. +If you want to get a little more advanced, style guides and linters can help standardize project contributions and make them easier to review and accept. However, if your standards are too complicated, they can increase the barriers to contribution, so proceed carefully here and make sure you're only adding just enough rules to make everyone's lives easier. -Hopefully, you’re feeling more empowered to say no, set and enforce rules, and take breaks when you need them. In the next section, we’ll talk about how you can leverage your community to grow a sustainable project. +Hopefully, you're feeling more empowered to say no, set and enforce rules, and take breaks when you need them. In the next section, we'll talk about how you can leverage your community to grow a sustainable project. ## Further reading @@ -95,5 +95,5 @@ Hopefully, you’re feeling more empowered to say no, set and enforce rules, and * [A Plea for Better Open Source Etiquette](https://blog.quickpeople.co.uk/2013/04/14/a-plea-for-better-open-source-etiquette/) by @benilovj * [How to be an open source gardener](http://words.steveklabnik.com/how-to-be-an-open-source-gardener) by @steveklabnik * [Kindly Closing Pull Requests](https://github.com/blog/2124-kindly-closing-pull-requests) by @MikeMcQuaid -* [My condolences, you’re now the maintainer of a popular open source project](https://runcommand.io/2016/06/26/my-condolences-youre-now-the-maintainer-of-a-popular-open-source-project/) by @danielbachhuber +* [My condolences, you're now the maintainer of a popular open source project](https://runcommand.io/2016/06/26/my-condolences-youre-now-the-maintainer-of-a-popular-open-source-project/) by @danielbachhuber * [Handling Large OSS Projects Defensively](http://artsy.github.io/blog/2016/07/03/handling-big-projects/) by @orta diff --git a/sustaining/healthy-communities.md b/sustaining/healthy-communities.md index 5237fe8732d..6ffec1e7c19 100644 --- a/sustaining/healthy-communities.md +++ b/sustaining/healthy-communities.md @@ -3,34 +3,34 @@ title: Sustaining Healthy Communities next: sustaining/leadership.md --- -Your project’s community is extremely powerful. That power can be a blessing or a curse, depending on how you wield it. In this section, we’ll look at ways to structure your community to become a force of construction, not destruction. +Your project's community is extremely powerful. That power can be a blessing or a curse, depending on how you wield it. In this section, we'll look at ways to structure your community to become a force of construction, not destruction. -If you’re starting an open source project today, the vast majority of contributors will be "casual contributors": people who contribute to a project only occasionally. Sometimes these are also called “drive-by contributors”. +If you're starting an open source project today, the vast majority of contributors will be "casual contributors": people who contribute to a project only occasionally. Sometimes these are also called "drive-by contributors". A casual contributor may not have time to get fully up to speed with your project. Nearly half of contributors on popular GitHub projects, for example, only made one contribution.[^1] This level of noise can be overwhelming at first. But the more people feel ownership of your project, the more work can be distributed.[^2] It will be much less stressful than trying to do everything yourself. [^1]: [More Common Than You Think: An In-Depth Study of Casual Contributors](http://gustavopinto.org/lost+found/saner2016.pdf) [^2]: [Node.js](https://github.com/nodejs) is a big project that helped popularize some of these ideas. See [Building a Better Node Community.](https://medium.com/node-js-javascript/building-a-better-node-community-3f8f45b45cb5) -Here are some ways you can empower your biggest fans to run with the work they’re excited about. +Here are some ways you can empower your biggest fans to run with the work they're excited about. -## Meet contributors where they’re at +## Meet contributors where they're at -Good documentation is important to give casual contributors the context they need. Make sure people know what the goal of your project is and whether there are contributions you categorically won’t accept. +Good documentation is important to give casual contributors the context they need. Make sure people know what the goal of your project is and whether there are contributions you categorically won't accept. In your CONTRIBUTING.md file, explicitly tell new contributors how to get started. You may even want to make a dedicated section for this purpose. For example, [Read the Docs](http://docs.readthedocs.io/en/latest/contribute.html#contributing-to-development) tells its readers: -> If you want to deep dive and help out with development on Read the Docs, then first get the project installed locally according to the Installation Guide. After that is done we suggest you have a look at tickets in our issue tracker that are labelled Good First Bug. These are meant to be a great way to get a smooth start and won’t put you in front of the most complex parts of the system. +> If you want to deep dive and help out with development on Read the Docs, then first get the project installed locally according to the Installation Guide. After that is done we suggest you have a look at tickets in our issue tracker that are labelled Good First Bug. These are meant to be a great way to get a smooth start and won't put you in front of the most complex parts of the system. -In Issues, label bugs that are suitable for beginners: for example, _"good first bug"_, _“help wanted”_, or _“first-timers-only”_. These labels make it easy for someone new to your project to quickly scan your issues and get started. ([Here](https://github.com/librariesio/libraries.io/blob/6afea1a3354aef4672d9b3a9fc4cc308d60020c8/app/models/github_issue.rb#L8-L14) are some other examples of commonly used labels.) +In Issues, label bugs that are suitable for beginners: for example, _"good first bug"_, _"help wanted"_, or _"first-timers-only"_. These labels make it easy for someone new to your project to quickly scan your issues and get started. ([Here](https://github.com/librariesio/libraries.io/blob/6afea1a3354aef4672d9b3a9fc4cc308d60020c8/app/models/github_issue.rb#L8-L14) are some other examples of commonly used labels.) -Finally, use your documentation to make people feel welcome at every step of the way. Remember that you will never meet most of the people who come across your project. There are probably contributions you didn’t receive because somebody felt intimidated or didn’t know where to get started. Do your best to reduce your chances of someone leaving your project in frustration. Even a few kind words can help. For example, here’s how [Rubinius](https://github.com/rubinius/rubinius/blob/master/CONTRIBUTING.md) starts off its contributing guide: +Finally, use your documentation to make people feel welcome at every step of the way. Remember that you will never meet most of the people who come across your project. There are probably contributions you didn't receive because somebody felt intimidated or didn't know where to get started. Do your best to reduce your chances of someone leaving your project in frustration. Even a few kind words can help. For example, here's how [Rubinius](https://github.com/rubinius/rubinius/blob/master/CONTRIBUTING.md) starts off its contributing guide: > We want to start off by saying thank you for using Rubinius. This project is a labor of love, and we appreciate all of the users that catch bugs, make performance improvements, and help with documentation. Every contribution is meaningful, so thank you for participating. That being said, here are a few guidelines that we ask you to follow so we can successfully address your issue. ## Share ownership of your project -People are excited to contribute to projects when they feel like it belongs to them. That doesn’t mean you need to turn over your project’s vision or accept contributions you don’t want. But the more you can give credit to others, the more likely it is that they will stick around. +People are excited to contribute to projects when they feel like it belongs to them. That doesn't mean you need to turn over your project's vision or accept contributions you don't want. But the more you can give credit to others, the more likely it is that they will stick around. @orta found that this approach to ownership helped him succeed with his open source projects, including [Danger](https://github.com/danger/danger/): @@ -40,13 +40,13 @@ People are excited to contribute to projects when they feel like it belongs to t See if you can find ways to give credit to your community as much as possible. Here are some ideas: -* Resist fixing easy bugs. Instead, use them as opportunities to recruit new contributors, or mentor someone who’d like to contribute. It may seem unnatural at first, but your investment will pay off over time. +* Resist fixing easy bugs. Instead, use them as opportunities to recruit new contributors, or mentor someone who'd like to contribute. It may seem unnatural at first, but your investment will pay off over time. -* Start a CONTRIBUTORS.txt file in your project that lists everyone who’s contributed to your project. Here’s an example that @shazow made for his project, [urllib3](https://github.com/shazow/urllib3/blob/master/CONTRIBUTORS.txt). +* Start a CONTRIBUTORS.txt file in your project that lists everyone who's contributed to your project. Here's an example that @shazow made for his project, [urllib3](https://github.com/shazow/urllib3/blob/master/CONTRIBUTORS.txt). -* If you’ve got a sizeable community, consider sending out a newsletter or writing a blog post that calls out contributors and thanks them. Rust’s [This Week in Rust](https://this-week-in-rust.org/) and Hoodie’s [Shoutouts](http://hood.ie/blog/shoutouts-week-24.html) are two good examples. +* If you've got a sizeable community, consider sending out a newsletter or writing a blog post that calls out contributors and thanks them. Rust's [This Week in Rust](https://this-week-in-rust.org/) and Hoodie's [Shoutouts](http://hood.ie/blog/shoutouts-week-24.html) are two good examples. -* Consider giving every contributor commit access. @felixge found that this made people more excited to polish up their patches, and he even found new maintainers for projects that he hadn’t worked on in awhile. [^5] +* Consider giving every contributor commit access. @felixge found that this made people more excited to polish up their patches, and he even found new maintainers for projects that he hadn't worked on in awhile. [^5] [^5]: [The Pull Request Hack](http://felixge.de/2013/03/11/the-pull-request-hack.html) @@ -54,9 +54,9 @@ The bigger your project, and the bigger your community, the easier it is to find [^6]: [What is the Truck Factor of Popular GitHub Applications? A First Assessment](https://peerj.com/preprints/1233.pdf) -As you build a community of engaged and thoughtful people, you may start thinking about how to formalize their ownership in your project. In the next section, we’ll cover some commonly asked questions around leadership and governance. +As you build a community of engaged and thoughtful people, you may start thinking about how to formalize their ownership in your project. In the next section, we'll cover some commonly asked questions around leadership and governance. -## Don’t tolerate bad actors +## Don't tolerate bad actors Any popular project will inevitably attract people who harm, rather than help, your community. They may start unnecessary debates, quibble over trivial features, or bully others. @@ -68,7 +68,7 @@ When you see negative behavior happening on your project, call it out publicly. * [Growing a contributor base in modern open source](https://opensource.com/life/16/5/growing-contributor-base-modern-open-source) by @mikeal * [Sustainable Open Source](http://writing.jan.io/2015/11/20/sustainable-open-source.html) by @janl -* [Wharton’s Adam Grant on the key to professional success](http://www.mckinsey.com/business-functions/organization/our-insights/whartons-adam-grant-on-the-key-to-professional-success) +* [Wharton's Adam Grant on the key to professional success](http://www.mckinsey.com/business-functions/organization/our-insights/whartons-adam-grant-on-the-key-to-professional-success) * [How the Moya org handles contributions](https://github.com/Moya/contributors) * [Rust Governance](https://github.com/rust-lang/rfcs/blob/master/text/1068-rust-governance.md) * [How to use Github issues to attract new contributors](http://radek.io/2015/08/24/github-issues/) by @pazdera diff --git a/sustaining/index.md b/sustaining/index.md index b2288d30022..374217343fe 100644 --- a/sustaining/index.md +++ b/sustaining/index.md @@ -5,4 +5,4 @@ next: sustaining/best-practices.md Congratulations! You launched a project into the universe, and it managed to hit escape velocity. People are using your project, contributing back, and telling their friends. Your project has a bright future ahead of it. 👏 🚀 🌠 -Maybe you’re excited. Maybe you’re terrified. Maybe your inbox is overflowing with unanswered questions and unreviewed pull requests. Fear not, brave maintainer. This section of the Handbook is here to help. +Maybe you're excited. Maybe you're terrified. Maybe your inbox is overflowing with unanswered questions and unreviewed pull requests. Fear not, brave maintainer. This section of the Handbook is here to help. diff --git a/sustaining/leadership.md b/sustaining/leadership.md index 1e4159f200d..7aec587c64e 100644 --- a/sustaining/leadership.md +++ b/sustaining/leadership.md @@ -3,9 +3,9 @@ title: Leadership & Governance next: troubleshooting/index.md --- -Your project is growing, people are engaged, and you’re committed to keeping this thing going. At this stage, you’re probably starting to wonder about governance. Maybe you want to recognize a community members who’s made significant contributions to your project. Maybe you’ve gotten into a debate with your community and realized you didn’t know how to resolve it. +Your project is growing, people are engaged, and you're committed to keeping this thing going. At this stage, you're probably starting to wonder about governance. Maybe you want to recognize a community members who's made significant contributions to your project. Maybe you've gotten into a debate with your community and realized you didn't know how to resolve it. -In this section, we’ll answer some commonly asked questions about leadership and governance for open source projects. +In this section, we'll answer some commonly asked questions about leadership and governance for open source projects. ## Table of Contents @@ -26,23 +26,23 @@ There are three common governance structures associated with open source project * **Liberal contribution:** Under a liberal contribution model, the people who do the most work are recognized as most influential, but this is based on current work and not historic contributions. Major project decisions are made based on a consensus seeking process (discuss major grievances) rather than pure vote, and strive to include as many community perspectives as possible. The liberal contribution model was pioneered by [Node.js](https://nodejs.org/en/foundation/). [Rust](https://www.rust-lang.org/en-US/) is another example. -Which one should you use? It's up to you! There is no one correct model. Each one has advantages and tradeoffs. And although they may seem quite different at first, all three models have more in common than it might seem. If you’re interested in adopting one of these models, here are some templates: +Which one should you use? It's up to you! There is no one correct model. Each one has advantages and tradeoffs. And although they may seem quite different at first, all three models have more in common than it might seem. If you're interested in adopting one of these models, here are some templates: * [BDFL model template](http://oss-watch.ac.uk/resources/benevolentdictatorgovernancemodel) * [Meritocracy model template](http://oss-watch.ac.uk/resources/meritocraticgovernancemodel) -* [Node.js’s liberal contribution policy](https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.m9ht26e79) +* [Node.js's liberal contribution policy](https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.m9ht26e79) ## Do I need governance docs when I launch my project? -It’s not necessary to define your project’s governance when you launch. The best part about open source governance is that it is shaped by the community! +It's not necessary to define your project's governance when you launch. The best part about open source governance is that it is shaped by the community! -There is no right time to write down your project’s governance, but it’s much easier to define once you’ve seen your community dynamics play out. However, some documentation will inevitably contribute to your project’s governance, so start writing down what you can. For example, you can define clear expectations for behavior, or how your contributor process works, even at your project’s launch. And if you’re a company launching an open source project, you may also want to explain anything particular to how your company will (or won’t!) be involved with the project. +There is no right time to write down your project's governance, but it's much easier to define once you've seen your community dynamics play out. However, some documentation will inevitably contribute to your project's governance, so start writing down what you can. For example, you can define clear expectations for behavior, or how your contributor process works, even at your project's launch. And if you're a company launching an open source project, you may also want to explain anything particular to how your company will (or won't!) be involved with the project. ## When should I give someone commit access? -It’s up to you when you want to give someone commit access to your project. Some people think you should give commit access to everybody who makes a contribution. [^1] Doing so could encourage more people to feel ownership of your project. On the other hand, especially for big community projects, you may want to only give commit access to people who have made have demonstrated their commitment. There’s no one right way of doing it - do what makes you most comfortable! +It's up to you when you want to give someone commit access to your project. Some people think you should give commit access to everybody who makes a contribution. [^1] Doing so could encourage more people to feel ownership of your project. On the other hand, especially for big community projects, you may want to only give commit access to people who have made have demonstrated their commitment. There's no one right way of doing it - do what makes you most comfortable! [^1]: [The Pull Request Hack](http://felixge.de/2013/03/11/the-pull-request-hack.html) by @felixge @@ -60,15 +60,15 @@ Here are some common roles that you might have heard of for open source projects [^2]: [Healthy Open Source](https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951) by @mikeal -For some projects, "maintainers" are the only people in a project with commit access. In other projects, they’re simply the people who are listed in the README as maintainers. +For some projects, "maintainers" are the only people in a project with commit access. In other projects, they're simply the people who are listed in the README as maintainers. -A maintainer doesn’t necessarily have to be someone who writes code for your project. It could be someone who’s done a lot of work evangelizing your project (like @janl did for [CouchDB](https://github.com/apache/couchdb)) or written documentation that made the project more accessible to others (like @orta did for [CocoaPods](https://github.com/CocoaPods/CocoaPods)). [^3] Regardless of what they do day-to-day, a maintainer is probably someone who feels responsibility over the direction of the project and is committed to improving it. +A maintainer doesn't necessarily have to be someone who writes code for your project. It could be someone who's done a lot of work evangelizing your project (like @janl did for [CouchDB](https://github.com/apache/couchdb)) or written documentation that made the project more accessible to others (like @orta did for [CocoaPods](https://github.com/CocoaPods/CocoaPods)). [^3] Regardless of what they do day-to-day, a maintainer is probably someone who feels responsibility over the direction of the project and is committed to improving it. [^3]: [From Orta](https://realm.io/news/orta-therox-moving-to-oss-by-default/): - > I’ve been renowned for my work on CocoaPods, but most people don’t know that I actually don’t do any real work on the CocoaPods tool itself. My time on the project is mostly spent doing things like documentation and working on branding. + > I've been renowned for my work on CocoaPods, but most people don't know that I actually don't do any real work on the CocoaPods tool itself. My time on the project is mostly spent doing things like documentation and working on branding. -You should use leadership roles to formally recognize people who have made outstanding contributions to your project, regardless of their technical skill. @jacobian, one of [Django](https://github.com/django/django)’s former BDFLs, once told a crowd at PyCon that he is actually a mediocre programmer who joined the project a year after it started, even though he’s often mistaken as the co-creator or even "inventor" of Django. [^4] +You should use leadership roles to formally recognize people who have made outstanding contributions to your project, regardless of their technical skill. @jacobian, one of [Django](https://github.com/django/django)'s former BDFLs, once told a crowd at PyCon that he is actually a mediocre programmer who joined the project a year after it started, even though he's often mistaken as the co-creator or even "inventor" of Django. [^4] [^4]: [Pycon 2015 Keynote](https://www.youtube.com/watch?v=hIJdFxYlEKE#t=5m0s) by @jacobian @@ -76,7 +76,7 @@ You should use leadership roles to formally recognize people who have made outst Formalizing your leadership roles helps people take ownership and tells other community members who to look to for help. For a smaller project, designating leaders can be as simple as adding their names to your README. You could also create a separate text file that lists the names of project leaders. If your project has a website, you can create a team page or list your project leaders there. -If your project is bigger, you may have a "core team" of maintainers, or even subcommittees of people who take ownership of different issue areas. [Rust](https://github.com/rust-lang/rust) is an example of a project that moved from having one core team to multiple teams. [^5] For example, you could have subcommittees focused on security, issue triaging, or community conduct. Let people self-organize and volunteer for the roles they’re most excited about, rather than assigning them. +If your project is bigger, you may have a "core team" of maintainers, or even subcommittees of people who take ownership of different issue areas. [Rust](https://github.com/rust-lang/rust) is an example of a project that moved from having one core team to multiple teams. [^5] For example, you could have subcommittees focused on security, issue triaging, or community conduct. Let people self-organize and volunteer for the roles they're most excited about, rather than assigning them. [^5]: [The Rust Team](https://www.rust-lang.org/en-US/team.html) @@ -84,15 +84,15 @@ Leadership teams may want to create a designated channel (like on IRC) or meet r [^6]: [Talking with other devs](https://github.com/cucumber/cucumber-ruby/blob/master/CONTRIBUTING.md#talking-with-other-devs) from [Cucumber-ruby](https://github.com/cucumber/cucumber-ruby) -Once you’ve established leadership roles, don’t forget to document how people can attain them! Establish a clear process for how someone can become a maintainer or join a subcommittee in your project, and write it into your GOVERNANCE.md. Documenting this information avoids the community perception that maintainers are a clique that makes its decisions in private. +Once you've established leadership roles, don't forget to document how people can attain them! Establish a clear process for how someone can become a maintainer or join a subcommittee in your project, and write it into your GOVERNANCE.md. Documenting this information avoids the community perception that maintainers are a clique that makes its decisions in private. -Finally, if your project is on GitHub, consider moving your project from your personal account to an Organization. [GitHub Organizations](https://github.com/blog/674-introducing-organizations) make it easier to manage permissions and help protect your project’s legacy. +Finally, if your project is on GitHub, consider moving your project from your personal account to an Organization. [GitHub Organizations](https://github.com/blog/674-introducing-organizations) make it easier to manage permissions and help protect your project's legacy. ## Do I need a legal entity to support my project? -You don’t need a legal entity to support your open source project unless you’re handling money. For example, if you want to create a commercial business, you’ll want to set up a C Corp or LLC (if you’re based in the US). If you’re just doing contract work related to your open source project, you can accept money as a sole proprietor, or set up an LLC (if you’re based in the US). +You don't need a legal entity to support your open source project unless you're handling money. For example, if you want to create a commercial business, you'll want to set up a C Corp or LLC (if you're based in the US). If you're just doing contract work related to your open source project, you can accept money as a sole proprietor, or set up an LLC (if you're based in the US). -If you want to accept donations for your open source project, you can set up a donation button (using PayPal or Stripe, for example), but the money won’t be tax-deductible unless you are a nonprofit (such as a 501c3 or 501c6, if you’re in the US). Many projects don’t wish to go through the trouble of setting up a nonprofit, so they find a nonprofit fiscal sponsor instead. A fiscal sponsor accepts donations on your behalf, usually in exchange for a percentage of the donation. [Software Freedom Conservancy](https://sfconservancy.org/), [Apache Foundation](http://www.apache.org/), [Eclipse Foundation](https://eclipse.org/org/foundation/), and [Open Collective](https://opencollective.com/opensource) are examples of organizations that serve as fiscal sponsors for open source projects. +If you want to accept donations for your open source project, you can set up a donation button (using PayPal or Stripe, for example), but the money won't be tax-deductible unless you are a nonprofit (such as a 501c3 or 501c6, if you're in the US). Many projects don't wish to go through the trouble of setting up a nonprofit, so they find a nonprofit fiscal sponsor instead. A fiscal sponsor accepts donations on your behalf, usually in exchange for a percentage of the donation. [Software Freedom Conservancy](https://sfconservancy.org/), [Apache Foundation](http://www.apache.org/), [Eclipse Foundation](https://eclipse.org/org/foundation/), and [Open Collective](https://opencollective.com/opensource) are examples of organizations that serve as fiscal sponsors for open source projects. If your project is closely associated with a certain language or ecosystem, there may also be a related software foundation you can work with. For example, the [Python Software Foundation](https://www.python.org/psf/) helps support [PyPI](https://pypi.python.org/pypi), the Python package manager, and the [Node.js Foundation](https://nodejs.org/en/foundation/) helps support [Express.js](http://expressjs.com/), a Node-based framework. diff --git a/troubleshooting/burnout.md b/troubleshooting/burnout.md index bab8616952d..c5eb8101899 100644 --- a/troubleshooting/burnout.md +++ b/troubleshooting/burnout.md @@ -2,40 +2,40 @@ 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. +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. +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. +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. +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 best practices for maintainers [here](../../sustaining/best-practices/). +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 best practices for maintainers [here](../../sustaining/best-practices/). ## 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. +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. +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 +## 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. +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. +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 +## 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! +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: * [Leadership, Guilt, and Pull Requests](http://progrium.com/blog/2015/12/04/leadership-guilt-and-pull-requests/) by @progrium -* [Why I Haven’t Fixed Your Issue Yet](https://archive.is/j8zAk) by @michaelbromley -* [The Open Source Maintainer’s Dilemma](https://publicobject.com/2016/05/03/the-open-source-maintainers-dilemma/) by @swankjesse +* [Why I Haven't Fixed Your Issue Yet](https://archive.is/j8zAk) by @michaelbromley +* [The Open Source Maintainer's Dilemma](https://publicobject.com/2016/05/03/the-open-source-maintainers-dilemma/) by @swankjesse diff --git a/troubleshooting/conduct.md b/troubleshooting/conduct.md index 1d850a55c93..d6a6f5f4e62 100644 --- a/troubleshooting/conduct.md +++ b/troubleshooting/conduct.md @@ -2,11 +2,11 @@ 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. +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 +## 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: +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. @@ -16,7 +16,7 @@ Ideally, you’ve explained how your code of conduct will be enforced **_before_ 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 and @mr-c explain on their project, [Khmer](https://github.com/dib-lab/khmer): +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 and @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] @@ -24,21 +24,21 @@ Don’t forget that someone might want to report a violation about someone who u ## 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. +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. +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. +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. +* 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: @@ -48,7 +48,7 @@ Sometimes, a resolution cannot be reached. The person in question may become agg 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. +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. ## Further reading diff --git a/troubleshooting/contributions.md b/troubleshooting/contributions.md index 77979d9e142..b1ed2cbe151 100644 --- a/troubleshooting/contributions.md +++ b/troubleshooting/contributions.md @@ -2,32 +2,32 @@ 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. +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. +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. +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. +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 +## 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. +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. +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. +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. +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. +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. +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. diff --git a/troubleshooting/finding-consensus.md b/troubleshooting/finding-consensus.md index 49431308235..d5799ff1903 100644 --- a/troubleshooting/finding-consensus.md +++ b/troubleshooting/finding-consensus.md @@ -4,9 +4,9 @@ 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. +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. +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 @@ -14,39 +14,39 @@ When your community is grappling with a difficult issue, tempers may rise. Peopl 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. 🙏 +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. +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. +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. +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. +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. +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. +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. +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. +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. diff --git a/troubleshooting/getting-paid.md b/troubleshooting/getting-paid.md index df8473dac10..ee44ddcc981 100644 --- a/troubleshooting/getting-paid.md +++ b/troubleshooting/getting-paid.md @@ -2,7 +2,7 @@ title: Getting paid for open source work --- -If you make regular, substantial contributions to open source, or you’re just considering your first contribution, you may start to wonder whether anybody gets paid to work on open source. +If you make regular, substantial contributions to open source, or you're just considering your first contribution, you may start to wonder whether anybody gets paid to work on open source. Today, some open source work is paid. Projects sometimes raise money from companies, individuals, or others to fund ongoing work. [Ruby Together](https://rubytogether.org/), for example, is a foundation that pays for work on [bundler](https://github.com/bundler/bundler), [RubyGems](https://github.com/rubygems/rubygems), and other Ruby infrastructure projects. @@ -10,13 +10,13 @@ For an individual contributor, a company may hire an employee to work on an open Other open source work is unpaid or volunteered. For example, someone might come across a bug in a project they use and submit a quick fix, or they might enjoy tinkering with an open source project in their spare time. (Did you know that @gvanrossum started [Python](https://github.com/python) over a Christmas holiday?) -There are plenty of reasons why a person or project would not want to be paid for open source work. They may already have a full-time job that they love, which enables them to contribute to open source in their spare time. Others enjoy thinking of open source as a hobby or creative escape and don’t want to feel financially obligated to work on their projects. +There are plenty of reasons why a person or project would not want to be paid for open source work. They may already have a full-time job that they love, which enables them to contribute to open source in their spare time. Others enjoy thinking of open source as a hobby or creative escape and don't want to feel financially obligated to work on their projects. For others, getting paid to contribute to open source is the only way they can afford to make it work. Maintaining popular projects can be a significant responsibility, taking up 10 or 20 hours per week instead of a few hours per month. -Paid work also allows people from different walks of life to make meaningful contributions. Some people cannot afford to spend unpaid time on open source projects, based on their current financial position or family situation. That means we miss out on many potential contributions from talented people who can’t afford to volunteer their time. +Paid work also allows people from different walks of life to make meaningful contributions. Some people cannot afford to spend unpaid time on open source projects, based on their current financial position or family situation. That means we miss out on many potential contributions from talented people who can't afford to volunteer their time. -As open source’s popularity increases, availability of funding has not yet caught up to the need. If you are interested in finding funding for your open source work, there are some options available to you. Here are some examples: +As open source's popularity increases, availability of funding has not yet caught up to the need. If you are interested in finding funding for your open source work, there are some options available to you. Here are some examples: * Raise money for your work through crowdfunding campaigns or donations. This works well if you have a strong audience or reputation already. @@ -24,7 +24,7 @@ As open source’s popularity increases, availability of funding has not yet cau * If you have a large project, you could raise money from companies and individual donors through a software foundation. Or you might try to start a business to support the project. -If you’d like to explore other different funding options, you can check out [this list](https://github.com/nayafia/lemonade-stand). Different types of funding require different skills, so consider your strengths to figure out which funding option works best for you. +If you'd like to explore other different funding options, you can check out [this list](https://github.com/nayafia/lemonade-stand). Different types of funding require different skills, so consider your strengths to figure out which funding option works best for you. ## Further reading diff --git a/troubleshooting/index.md b/troubleshooting/index.md index 99de724138e..d7ee58b8935 100644 --- a/troubleshooting/index.md +++ b/troubleshooting/index.md @@ -4,9 +4,9 @@ title: Troubleshooting This section of the handbook addresses some common situations or questions that may come up as you maintain your open source project. -These topics aren’t fun. They may feel unfamiliar or force you out of your comfort zone. No matter what you do, people may feel upset or criticize how you handled the situation. +These topics aren't fun. They may feel unfamiliar or force you out of your comfort zone. No matter what you do, people may feel upset or criticize how you handled the situation. -Sometimes, being a maintainer is a thankless job. If you’re reading this section, though, you’ve taken an important first step towards becoming a leader, and for that, we thank you. ❤️ +Sometimes, being a maintainer is a thankless job. If you're reading this section, though, you've taken an important first step towards becoming a leader, and for that, we thank you. ❤️ ## Troubleshooting topics From 925c40b6062707af737d2162490089708ef1866e Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Thu, 18 Aug 2016 21:27:55 +0200 Subject: [PATCH 2/2] Add linting for quote style Add linting of prose for quote and apostrophe style (preferring straight over smart marks). --- package.json | 1 + script/test-prose | 2 ++ 2 files changed, 3 insertions(+) diff --git a/package.json b/package.json index b79f7a0a05b..6954b4b8338 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,7 @@ "retext": "^3.0.0", "retext-english": "^2.0.0", "retext-equality": "^2.3.2", + "retext-quotes": "^1.0.0", "retext-readability": "^2.0.0", "retext-sentence-spacing": "^1.0.0", "retext-simplify": "^2.0.0", diff --git a/script/test-prose b/script/test-prose index 17efca79178..6df99b9959d 100755 --- a/script/test-prose +++ b/script/test-prose @@ -10,6 +10,7 @@ var remark2retext = require('remark-retext'); var stringify = require('remark-stringify'); var english = require('retext-english'); var sentenceSpacing = require('retext-sentence-spacing'); +var quotes = require('retext-quotes'); // Util stuff var report = require('vfile-reporter'); @@ -60,6 +61,7 @@ async.map(ignore.filter(glob.sync("**/*.md")), function(file, callback) { .use(remark2retext, unified() .use(english) .use(sentenceSpacing, {preferred: 1}) + .use(quotes, {preferred: 'straight'}) // .use(require('retext-simplify'), options["simplify"]) // .use(require('retext-equality')) // .use(require('retext-readability'), options["readability"])