From f8ce4b0149b913fa833bc36b268e6b10f0c0ffa3 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sat, 13 Aug 2016 13:53:04 -0500 Subject: [PATCH 1/2] Enable GFM and footnotes in linter --- script/test-prose | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/script/test-prose b/script/test-prose index fa9a992f025..675296d2f15 100755 --- a/script/test-prose +++ b/script/test-prose @@ -19,6 +19,12 @@ var jekyllConfig = yaml.safeLoad(fs.readFileSync('_config.yml', 'utf8')); var ignore = require('ignore')().add(jekyllConfig["exclude"]) var options = { + // https://github.com/wooorm/remark/tree/master/packages/remark-parse#options + "remark": { + "gfm": true, + "footnotes": true + }, + // https://github.com/wooorm/remark-lint/blob/master/doc/rules.md "lint": { "list-item-indent": "space", // As the gods intended. @@ -55,7 +61,7 @@ async.map(ignore.filter(glob.sync("**/*.md")), function(file, callback) { // .use(require('retext-readability'), options["readability"]) // ) .use(stringify) - .process(contents.toString(), function (err, result) { + .process(contents.toString(), options["remark"], function (err, result) { result.filename = file; callback(err, result); }); From 1898a6dcf62ee35cc2eb2699f7061bf2541a7a3f Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Sat, 13 Aug 2016 14:24:58 -0500 Subject: [PATCH 2/2] Use proper footnote references --- getting-started/branding.md | 10 ++++---- marketing/building-community.md | 18 +++++++-------- marketing/spreading-word.md | 18 +++++++-------- sustaining/best-practices.md | 22 ++++++++---------- sustaining/healthy-communities.md | 33 ++++++++++++--------------- sustaining/leadership.md | 38 +++++++++++++++---------------- troubleshooting/conduct.md | 14 +++++------- 7 files changed, 69 insertions(+), 84 deletions(-) diff --git a/getting-started/branding.md b/getting-started/branding.md index 6e294264e3c..b248c4e9af6 100644 --- a/getting-started/branding.md +++ b/getting-started/branding.md @@ -31,9 +31,11 @@ Throughout the life of your project, you’ll do a lot of writing: READMEs, tuto [@janl](https://github.com/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] -*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](https://github.com/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. @@ -41,10 +43,6 @@ It isn’t necessary to write a style guide for your project when you’re just We’re almost there! Next, we’ll walk you through a few components that every open source project should include when you launch. -## Footnotes - -[1] [http://writing.jan.io/2015/11/20/sustainable-open-source.html](http://writing.jan.io/2015/11/20/sustainable-open-source.html) - ## Further reading * [http://producingoss.com/en/getting-started.html#choosing-a-name](http://producingoss.com/en/getting-started.html#choosing-a-name) diff --git a/marketing/building-community.md b/marketing/building-community.md index 70bc1bc746b..c04f583811c 100644 --- a/marketing/building-community.md +++ b/marketing/building-community.md @@ -31,13 +31,17 @@ Documenting your open source project means more than just technical documentatio As you promote your project, people will probably have feedback and ideas for you. They may request support or functionality, have questions about how things work, or need help getting started. -Try to be responsive when someone files an issue, submits a pull request, or asks a question about your project. When you respond quickly, people will feel they are part of a dialogue, and feel more enthusiastic about participating in and using your project. For example, when Mozilla studied its community and engagement in 2014, they found that contributors who received code reviews within 48 hours had a much higher rate of return and repeat contribution. [1] +Try to be responsive when someone files an issue, submits a pull request, or asks a question about your project. When you respond quickly, people will feel they are part of a dialogue, and feel more enthusiastic about participating in and using your project. For example, when Mozilla studied its community and engagement in 2014, they found that contributors who received code reviews within 48 hours had a much higher rate of return and repeat contribution.[^1] + +[^1]: https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177 Remember that conversations about your project could also be happening in other places around the Internet, such as Stack Overflow, Twitter, or Reddit. You can set up notifications in some of these places so you are alerted when someone mentions your project. ## Make it easy for people to use and contribute -One way to think about your project’s community is what [@MikeMcQuaid](https://github.com/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](https://github.com/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]: https://speakerdeck.com/mikemcquaid/the-open-source-contributor-funnel As you build your community, consider how someone at the top of the funnel (a potential user) might theoretically make their way to the bottom (an active maintainer). Your goal is to make each stage of the contributor experience as frictionless as possible. When people have easy wins, they will feel incentivized to do more. @@ -47,17 +51,11 @@ For casual or first-time contributors, be open-minded about the types of contrib 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. -## Footnotes - -[1] [https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177](https://docs.google.com/presentation/d/1hsJLv1ieSqtXBzd5YZusY-mB8e1VJzaeOmh8Q4VeMio/edit#slide=id.g43d857af8_0177) - -[2] [https://speakerdeck.com/mikemcquaid/the-open-source-contributor-funnel](https://speakerdeck.com/mikemcquaid/the-open-source-contributor-funnel) - ## Further reading -* [http://radek.io/2015/10/12/marketing-for-open-source-projects-5/](http://radek.io/2015/10/12/marketing-for-open-source-projects-5/) +* [http://radek.io/2015/10/12/marketing-for-open-source-projects-5/](http://radek.io/2015/10/12/marketing-for-open-source-projects-5/) -* [http://hood.ie/blog/welcoming-communities.html](http://hood.ie/blog/welcoming-communities.html) +* [http://hood.ie/blog/welcoming-communities.html](http://hood.ie/blog/welcoming-communities.html) * [https://ashfurrow.com/blog/building-popular-projects/](https://ashfurrow.com/blog/building-popular-projects/) diff --git a/marketing/spreading-word.md b/marketing/spreading-word.md index e0bdd2ef9cc..cecff57d5ca 100644 --- a/marketing/spreading-word.md +++ b/marketing/spreading-word.md @@ -19,7 +19,9 @@ There is no magical formula to building an audience and reputation. Gaining the 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](https://github.com/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. +Consider creating a website for your project. [@adrianholovaty](https://github.com/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. + +[^1]: https://news.ycombinator.com/item?id=7531689 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. @@ -37,7 +39,9 @@ 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](https://github.com/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](https://github.com/mitchellh) attributes [Vagrant](https://github.com/mitchellh/vagrant)’s growth and popularity to the talks he gave about the project. [^2] + +[^2]: 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. @@ -47,17 +51,11 @@ Spreading the word is an important step in growing the popularity of your projec In the next section, we’ll talk about how to retain those early enthusiasts and grow an engaged community around your project. -## Footnotes - -[1] [https://news.ycombinator.com/item?id=7531689](https://news.ycombinator.com/item?id=7531689) - -[2] [https://github.com/swinton/codeconf/blob/master/the-hashicorp-formula-to-open-source.md](https://github.com/swinton/codeconf/blob/master/the-hashicorp-formula-to-open-source.md) - ## Further reading -* [https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/](https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/) +* [https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/](https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/) -* [https://zachholman.com/posts/open-source-marketing/](https://zachholman.com/posts/open-source-marketing/) +* [https://zachholman.com/posts/open-source-marketing/](https://zachholman.com/posts/open-source-marketing/) * [http://readwrite.com/2014/10/10/open-source-marketing-apache-storm-nathan-merz/](http://readwrite.com/2014/10/10/open-source-marketing-apache-storm-nathan-merz/) diff --git a/sustaining/best-practices.md b/sustaining/best-practices.md index 4bdb5900210..921b9b71601 100644 --- a/sustaining/best-practices.md +++ b/sustaining/best-practices.md @@ -17,7 +17,9 @@ Be honest with yourself about how much time you have to spend on your project. T 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](https://github.com/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] +[@lord](https://github.com/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] + +[^1]: [https://lord.io/blog/2014/oss-tips/](https://lord.io/blog/2014/oss-tips/) 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. @@ -41,7 +43,9 @@ Some examples of rules you may want to write down: ## Learn to say no -The first rule of open source, according to [@shykes](https://github.com/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](https://github.com/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]: [https://twitter.com/solomonstre/status/715277134978113536](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. @@ -49,7 +53,9 @@ One of the most important places you’ll practice saying no is on your your iss 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](https://github.com/jfrazelle) put it: *"I’ve talked to maintainers from several different open source projects, Mesos, Kubernetes, C**hromium**, 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](https://github.com/jfrazelle) put it: *"I’ve talked to maintainers from several different open source projects, Mesos, Kubernetes, C**hromium**, 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]: [https://blog.jessfraz.com/post/the-art-of-closing/](https://blog.jessfraz.com/post/the-art-of-closing/) ## Keep communication public @@ -69,7 +75,7 @@ The good news about maintaining a popular open source project is that other main * [Vossibility](https://github.com/icecrime/vossibility-stack) pulls stats on your project -* [mention-bot ](https://github.com/facebook/mention-bot)automatically mentions potential reviewers for pull requests +* [mention-bot](https://github.com/facebook/mention-bot)automatically mentions potential reviewers for pull requests * [PullApprove](https://about.pullapprove.com/) helps you manage pull requests @@ -81,14 +87,6 @@ If you want to get a little more advanced, style guides and linters can help sta 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. -## Footnotes - -[1] [https://lord.io/blog/2014/oss-tips/](https://lord.io/blog/2014/oss-tips/) - -[2] [https://twitter.com/solomonstre/status/715277134978113536](https://twitter.com/solomonstre/status/715277134978113536) - -[3] [https://blog.jessfraz.com/post/the-art-of-closing/](https://blog.jessfraz.com/post/the-art-of-closing/) - ## Further reading * [http://www.kennethreitz.org/essays/be-cordial-or-be-on-your-way](http://www.kennethreitz.org/essays/be-cordial-or-be-on-your-way) diff --git a/sustaining/healthy-communities.md b/sustaining/healthy-communities.md index ab9efc58355..11f3c538f4c 100644 --- a/sustaining/healthy-communities.md +++ b/sustaining/healthy-communities.md @@ -7,7 +7,10 @@ Your project’s community is extremely powerful. That power can be a blessing o If you’re starting an open source project today, the vast majority of contributions will come from "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. +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. @@ -17,13 +20,13 @@ Good documentation is important to give casual contributors the context they nee 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.) 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.* +> 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 @@ -31,7 +34,9 @@ People are excited to contribute to projects when they feel like it belongs to t [@orta](https://github.com/orta) found that this approach to ownership helped him succeed with his open source projects, including [Danger](https://github.com/danger/danger/): -*Understanding motivations, encouraging ownership and accommodating multiple viewpoints are vital parts of anyone who wants to make a project bigger than themselves. There [are lots of times](https://github.com/danger/danger/graphs/contributors) when I'm not the lead developer on Danger. [4]* +> Understanding motivations, encouraging ownership and accommodating multiple viewpoints are vital parts of anyone who wants to make a project bigger than themselves. There [are lots of times](https://github.com/danger/danger/graphs/contributors) when I'm not the lead developer on Danger.[^danger] + +[^danger]: [Handling Large OSS Projects Defensively](http://artsy.github.io/blog/2016/07/03/handling-big-projects/) by [@orta](https://github.com/orta) See if you can find ways to give credit to your community as much as possible. Here are some ideas: @@ -41,9 +46,13 @@ See if you can find ways to give credit to your community as much as possible. H * 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](https://github.com/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](https://github.com/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) -The bigger your project, and the bigger your community, the easier it is to find help. The reality is that most projects only have one or two maintainers who do most of the work. [6] While you many not always find someone to answer the call, putting a Batsignal out there increases the chances that other people will pitch in. And the earlier you start, the sooner people can help. Early investments in your community will pay off over time. +The bigger your project, and the bigger your community, the easier it is to find help. The reality is that most projects only have one or two maintainers who do most of the work.[^6] While you many not always find someone to answer the call, putting a Batsignal out there increases the chances that other people will pitch in. And the earlier you start, the sooner people can help. Early investments in your community will pay off over time. + +[^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. @@ -55,18 +64,6 @@ Do your best to adopt a zero-tolerance policy towards these types of people. If When you see negative behavior happening on your project, call it out publicly. Explain, in a kind but firm tone, why their behavior is not acceptable. If the problem persists, you may need to [ask them to leave](../../troubleshooting/conduct/). Your code of conduct can be a constructive guide for these conversations. -## Footnotes - -[1] [http://gustavopinto.org/lost+found/saner2016.pdf](http://gustavopinto.org/lost+found/saner2016.pdf) - -[3] [Node.js](https://github.com/nodejs) is a big project that helped popularize some of these ideas: [https://medium.com/node-js-javascript/building-a-better-node-community-3f8f45b45cb5#.db5dkrbrw](https://medium.com/node-js-javascript/building-a-better-node-community-3f8f45b45cb5#.db5dkrbrw) - -[4] [http://artsy.github.io/blog/2016/07/03/handling-big-projects/](http://artsy.github.io/blog/2016/07/03/handling-big-projects/) - -[5] [http://felixge.de/2013/03/11/the-pull-request-hack.html](http://felixge.de/2013/03/11/the-pull-request-hack.html) - -[6] [https://peerj.com/preprints/1233.pdf](https://peerj.com/preprints/1233.pdf) - ## Further reading * [https://opensource.com/life/16/5/growing-contributor-base-modern-open-source](https://opensource.com/life/16/5/growing-contributor-base-modern-open-source) diff --git a/sustaining/leadership.md b/sustaining/leadership.md index 0dd310277ab..828cc753650 100644 --- a/sustaining/leadership.md +++ b/sustaining/leadership.md @@ -41,7 +41,9 @@ There is no right time to write down your project’s governance, but it’s muc ## 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]: [http://felixge.de/2013/03/11/the-pull-request-hack.html](http://felixge.de/2013/03/11/the-pull-request-hack.html) ## What are some leadership roles or responsibilities that projects use? @@ -53,21 +55,31 @@ Here are some common roles that you might have heard of for open source projects * Committer -[Node.js](https://github.com/nodejs), for example, defines a "contributor" as anyone who comments on an issue or pull request, whereas other projects would define a contributor as somebody whose pull request was accepted. [2] +[Node.js](https://github.com/nodejs), for example, defines a "contributor" as anyone who comments on an issue or pull request, whereas other projects would define a contributor as somebody whose pull request was accepted. [^2] + +[^2]: [https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.46vkbdar7](https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.46vkbdar7) 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](https://github.com/janl) did for [CouchDB](https://github.com/apache/couchdb)) or written documentation that made the project more accessible to others (like [@orta](https://github.com/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](https://github.com/janl) did for [CouchDB](https://github.com/apache/couchdb)) or written documentation that made the project more accessible to others (like [@orta](https://github.com/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: *"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."* [https://realm.io/news/orta-therox-moving-to-oss-by-default/](https://realm.io/news/orta-therox-moving-to-oss-by-default/) + +You should use leadership roles to formally recognize people who have made outstanding contributions to your project, regardless of their technical skill. [@jacobian](https://github.com/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](https://github.com/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]: [https://www.youtube.com/watch?v=hIJdFxYlEKE#t=5m0s](https://www.youtube.com/watch?v=hIJdFxYlEKE#t=5m0s) ## How do I formalize leadership roles in my project? 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. -Leadership teams may want to create a designated channel (like on IRC) or meet regularly to discuss the project (like on Gitter or Google Hangout). You can even make those meetings public so other people can listen. [Cucumber-ruby](https://github.com/cucumber/cucumber-ruby), for example, hosts office hours every week. [6] +[^5]: [https://www.rust-lang.org/en-US/team.html](https://www.rust-lang.org/en-US/team.html) + +Leadership teams may want to create a designated channel (like on IRC) or meet regularly to discuss the project (like on Gitter or Google Hangout). You can even make those meetings public so other people can listen. [Cucumber-ruby](https://github.com/cucumber/cucumber-ruby), for example, hosts office hours every week. [^6] + +[^6]: [https://github.com/cucumber/cucumber-ruby/blob/master/CONTRIBUTING.md#talking-with-other-devs](https://github.com/cucumber/cucumber-ruby/blob/master/CONTRIBUTING.md#talking-with-other-devs) 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. @@ -86,17 +98,3 @@ If your project is closely associated with a certain language or ecosystem, ther Congratulations on making it this far, and welcome to the ranks of open source maintainership! We hope your project continues to thrive and that this Handbook has helped you along the way. As you grow into your leadership role, you'll inevitably come across some tough situations. Check out our [Troubleshooting](../../troubleshooting/) section for help when you need it. And from the bottom of our hearts, thank you for sharing your work and making a positive contribution to the world. 💕 - -## Footnotes - -[1] [http://felixge.de/2013/03/11/the-pull-request-hack.html](http://felixge.de/2013/03/11/the-pull-request-hack.html) - -[2] [https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.46vkbdar7](https://medium.com/the-javascript-collection/healthy-open-source-967fa8be7951#.46vkbdar7) - -[3] From Orta: *"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."* [https://realm.io/news/orta-therox-moving-to-oss-by-default/](https://realm.io/news/orta-therox-moving-to-oss-by-default/) - -[4] [https://www.youtube.com/watch?v=hIJdFxYlEKE#t=5m0s](https://www.youtube.com/watch?v=hIJdFxYlEKE#t=5m0s) - -[5] [https://www.rust-lang.org/en-US/team.html](https://www.rust-lang.org/en-US/team.html) - -[6] [https://github.com/cucumber/cucumber-ruby/blob/master/CONTRIBUTING.md#talking-with-other-devs](https://github.com/cucumber/cucumber-ruby/blob/master/CONTRIBUTING.md#talking-with-other-devs) diff --git a/troubleshooting/conduct.md b/troubleshooting/conduct.md index c5d29fd7c30..8929e90d5a9 100644 --- a/troubleshooting/conduct.md +++ b/troubleshooting/conduct.md @@ -18,7 +18,9 @@ You should give people a private way (such as an email address) to report a code Don’t forget that someone might want to report a violation about someone who usually receives those reports. In this case, give them an option to report violations to someone else. For example, [@ctb](https://github.com/ctb) and [@mr-c](https://github.com/mr-c) explain on their project, [Khmer](https://github.com/dib-lab/khmer): -*Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by emailing **khmer-project@idyll.org** which only goes to C. Titus Brown and Michael R. Crusoe. To report an issue involving either of them please email **Judi Brown Clarke, Ph.D.** the Diversity Director at the BEACON Center for the Study of Evolution in Action, an NSF Center for Science and Technology.* [1] +> 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] + +[^1]: https://github.com/dib-lab/khmer/blob/master/CODE_OF_CONDUCT.rst ## Gather information about the situation @@ -44,20 +46,16 @@ Sometimes, a resolution cannot be reached. The person in question may become agg * Permanently ban the person from the project -Banning members should not be taken lightly and represents a permanent and irreconcilable difference of perspectives. You should only take these measures towards a community member when it is clear that a resolution cannot be reached. +Banning members should not be taken lightly and represents a permanent and irreconcilable difference of perspectives. You should only take these measures towards a community member when it is clear that a resolution cannot be reached. It’s not always easy to enforce your code of conduct, but this type of work is necessary to maintain a healthy and active community. When a project seems hostile or unwelcoming, even if it’s just one person whose behavior is tolerated by the rest of the community, you risk losing the contributions of many others, some of whom you may never even meet. -## Footnotes - -[1] [https://github.com/dib-lab/khmer/blob/master/CODE_OF_CONDUCT.rst](https://github.com/dib-lab/khmer/blob/master/CODE_OF_CONDUCT.rst) - ## Further reading * [https://www.djangoproject.com/conduct/enforcement-manual/](https://www.djangoproject.com/conduct/enforcement-manual/) -* [http://www.slideshare.net/aeschright/enforcing-your-code-of-conduct-effective-incident-response](http://www.slideshare.net/aeschright/enforcing-your-code-of-conduct-effective-incident-response) +* [http://www.slideshare.net/aeschright/enforcing-your-code-of-conduct-effective-incident-response](http://www.slideshare.net/aeschright/enforcing-your-code-of-conduct-effective-incident-response) -* [https://www.rust-lang.org/en-US/conduct.html](https://www.rust-lang.org/en-US/conduct.html) +* [https://www.rust-lang.org/en-US/conduct.html](https://www.rust-lang.org/en-US/conduct.html) * [http://producingoss.com/en/producingoss.html#difficult-people](http://producingoss.com/en/producingoss.html#difficult-people)