From dd0b06697037cbc8a367d28c47cdddc5b6ffd522 Mon Sep 17 00:00:00 2001 From: nayafia Date: Mon, 29 Aug 2016 16:48:43 -0700 Subject: [PATCH 1/3] add first draft of contributing guide --- CONTRIBUTING.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 73 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3729f9b0171..45c00e103ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,57 @@ -# Contributing +# Contributing to this Handbook -Please note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. +Thanks for checking out the Open Source Handbook! We're excited to hear and learn from you. Your experiences will benefit others who are reading and using this Handbook. -## Running the site locally +We've put together the following guidelines to: 1) communicate the goals of this project and 2) help you figure out where you can best be helpful. + +## Table of Contents +List all the headings here + +## Goals of this project + +We created this Handbook for individuals, communities and companies that want to successfully run and maintain an open source project. The content was originally created and curated by GitHub, along with input from outside community reviewers, but it is not specific to GitHub products. + +Here are some guiding principles for the Handbook: + +* **Approachability:** Don't assume reader has prior knowledge +* **Brevity:** Keep it simple, link to outside content for deeper dives +* **Curation:** Amplify community best practices vs. any individual's POV + +This Handbook is a jumping off point for people who want to familiarize themselves with running an open source project. It should give readers enough information to get started, but it doesn't attempt to answer everything in detail. + +This Handbook also aggregates community best practices, *not* what GitHub (or any other individual or entity) thinks is best. Therefore, we try to use examples and quotations from others to illustrate our points. Many sections also link to "Further Reading" at the end, to surface relevant writing and perspectives that lives elsewhere on the web. + +## Types of contributions we're looking for + +There are many ways you can contribute to the Handbook: + +* Fix editorial inconsistencies or inaccuracies +* Revise language to be more approachable and friendly +* Translate the Handbook into other languages +* Add links to other case studies or examples that help illustrate a point (either inline, or under "Further Reading") +* Write a new article (please open an issue to discuss before writing!) + +Interested in making a contribution? Read on! + +(should we call out anything we're NOT looking for here? would we accept design or code contributions?) + +## Ground rules & expectations + +Before we get started, here are a few things we expect from you (and that you should expect from others): + +* Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done". Try to listen to others rather than convince them that your way is correct. +* This Handbook is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project, you agree to abide by its terms. +* (anything we want to call out around testing?) + +## How to make a contribution + +If you're interested in contributing, start by searching through the [issues](https://github.com/github/open-source-handbook/issues) and [pull requests](https://github.com/github/open-source-handbook/pulls) to see whether someone else has raised a similar idea or question. + +If you don't see your idea listed, and you think it fits into the goals of this handbook, do one of the following: +* **If your contribution is minor,** such as a typo fix, you can make the change and open a pull request. +* **If your contribution is major,** such as a new article or case study, start by opening an issue first. That way, other people can weigh in on the discussion before you do any work. + +## Setting up your environment This site is powered by [Jekyll](jekyllrb.com). Running it on your local machine requires a working [Ruby](https://www.ruby-lang.org/en/) installation with [Bundler](http://bundler.io/). @@ -11,4 +60,24 @@ Once you have that set up, run: script/bootstrap script/server -…and open http://localhost:4000 in our web browser. +…and open http://localhost:4000 in your web browser. + +## Bug reports and security disclosures + +(do we need to include for this project?) + +## Contribution review process + +This repo is currently maintained by @nayafia and @bkeepers, who have commit access. They will likely review your contribution. + +While we enjoy maintaining this project and are excited that you want to participate, we have full-time jobs and competing priorities. If you haven't heard from anyone in 10 days, feel free to bump the thread or @-mention a maintainer to review your contribution. + +If you've been active on this project (such as writing helpful content, answering others' questions, or triaging issues) and would like a more formal leadership role, open up an issue and let's talk about it! + +## Community + +Handbook discussions take place on this repository's [Issues](https://github.com/github/open-source-handbook/issues) and [Pull Requests](https://github.com/github/open-source-handbook/pulls) sections. Anybody is welcome to join these conversations. + +There is also a mailing list for regular updates and discussion (link to mailing list) + +Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Not only will you stress them out, but keeping communication public means everybody can benefit and learn from the conversation. From c6a35f8a9f64ebb5988e92bb27573a88cc1b2865 Mon Sep 17 00:00:00 2001 From: Stephanie Wills Date: Tue, 30 Aug 2016 14:19:04 -0700 Subject: [PATCH 2/3] add one comma --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 45c00e103ce..2e7f8ce3408 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,7 +72,7 @@ This repo is currently maintained by @nayafia and @bkeepers, who have commit acc While we enjoy maintaining this project and are excited that you want to participate, we have full-time jobs and competing priorities. If you haven't heard from anyone in 10 days, feel free to bump the thread or @-mention a maintainer to review your contribution. -If you've been active on this project (such as writing helpful content, answering others' questions, or triaging issues) and would like a more formal leadership role, open up an issue and let's talk about it! +If you've been active on this project (such as writing helpful content, answering others' questions, or triaging issues) and would like a more formal leadership role, open up an issue, and let's talk about it! ## Community From 8f8992dd687b48f0f431deb0a6249e9aa806df7e Mon Sep 17 00:00:00 2001 From: Nadia Eghbal Date: Wed, 31 Aug 2016 16:01:48 -0700 Subject: [PATCH 3/3] incorporate edits --- CONTRIBUTING.md | 38 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2e7f8ce3408..a4fa5930b43 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,21 +5,27 @@ Thanks for checking out the Open Source Handbook! We're excited to hear and lear We've put together the following guidelines to: 1) communicate the goals of this project and 2) help you figure out where you can best be helpful. ## Table of Contents -List all the headings here +1. [Goals of this project](#goals-of-this-project) +2. [Types of contributions we're looking for](#types-of-contributions-were-looking-for) +3. [Ground rules & expectations](#ground-rules--expectations) +4. [How to contribute](#how-to-contribute) +5. [Setting up your environment](#setting-up-your-environment) +6. [Contribution review process](#contribution-review-process) +7. [Community](#community) ## Goals of this project -We created this Handbook for individuals, communities and companies that want to successfully run and maintain an open source project. The content was originally created and curated by GitHub, along with input from outside community reviewers, but it is not specific to GitHub products. +We created this Handbook for individuals, communities, and companies that want to successfully run and maintain an open source project. The content was originally created and curated by GitHub, along with input from outside community reviewers, but it is not specific to GitHub products. Here are some guiding principles for the Handbook: * **Approachability:** Don't assume reader has prior knowledge * **Brevity:** Keep it simple, link to outside content for deeper dives -* **Curation:** Amplify community best practices vs. any individual's POV +* **Curation:** Amplify community best practices vs. any individual's point of view -This Handbook is a jumping off point for people who want to familiarize themselves with running an open source project. It should give readers enough information to get started, but it doesn't attempt to answer everything in detail. +This Handbook is a jumping off point for people who want to learn how to run an open source project. It should give readers enough information to get started, but it doesn't attempt to answer everything in detail. -This Handbook also aggregates community best practices, *not* what GitHub (or any other individual or entity) thinks is best. Therefore, we try to use examples and quotations from others to illustrate our points. Many sections also link to "Further Reading" at the end, to surface relevant writing and perspectives that lives elsewhere on the web. +This Handbook also aggregates community best practices, *not* what GitHub (or any other individual or entity) thinks is best. Therefore, we try to use examples and quotations from others to illustrate our points. Many sections also link to "Further Reading" at the end, to surface relevant writing and perspectives that live elsewhere on the web. ## Types of contributions we're looking for @@ -33,19 +39,17 @@ There are many ways you can contribute to the Handbook: Interested in making a contribution? Read on! -(should we call out anything we're NOT looking for here? would we accept design or code contributions?) - ## Ground rules & expectations Before we get started, here are a few things we expect from you (and that you should expect from others): -* Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done". Try to listen to others rather than convince them that your way is correct. +* Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done." Try to listen to others rather than convince them that your way is correct. * This Handbook is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). By participating in this project, you agree to abide by its terms. -* (anything we want to call out around testing?) +* If you open a pull request, please ensure that your contribution passes all tests. If there are test failures, you will need to address them before we can merge your contribution. -## How to make a contribution +## How to contribute -If you're interested in contributing, start by searching through the [issues](https://github.com/github/open-source-handbook/issues) and [pull requests](https://github.com/github/open-source-handbook/pulls) to see whether someone else has raised a similar idea or question. +If you'd like to contribute, start by searching through the [issues](https://github.com/github/open-source-handbook/issues) and [pull requests](https://github.com/github/open-source-handbook/pulls) to see whether someone else has raised a similar idea or question. If you don't see your idea listed, and you think it fits into the goals of this handbook, do one of the following: * **If your contribution is minor,** such as a typo fix, you can make the change and open a pull request. @@ -62,22 +66,16 @@ Once you have that set up, run: …and open http://localhost:4000 in your web browser. -## Bug reports and security disclosures - -(do we need to include for this project?) - ## Contribution review process This repo is currently maintained by @nayafia and @bkeepers, who have commit access. They will likely review your contribution. While we enjoy maintaining this project and are excited that you want to participate, we have full-time jobs and competing priorities. If you haven't heard from anyone in 10 days, feel free to bump the thread or @-mention a maintainer to review your contribution. -If you've been active on this project (such as writing helpful content, answering others' questions, or triaging issues) and would like a more formal leadership role, open up an issue, and let's talk about it! +If you've been active on this project (such as writing helpful content, answering others' questions, or triaging issues) and would like a more formal leadership role, open up an issue and let's talk about it! ## Community -Handbook discussions take place on this repository's [Issues](https://github.com/github/open-source-handbook/issues) and [Pull Requests](https://github.com/github/open-source-handbook/pulls) sections. Anybody is welcome to join these conversations. - -There is also a mailing list for regular updates and discussion (link to mailing list) +Handbook discussions take place on this repository's [Issues](https://github.com/github/open-source-handbook/issues) and [Pull Requests](https://github.com/github/open-source-handbook/pulls) sections. Anybody is welcome to join these conversations. There is also a mailing list for regular updates and discussion. -Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Not only will you stress them out, but keeping communication public means everybody can benefit and learn from the conversation. +Wherever possible, do not take these conversations to private channels, including contacting the maintainers directly. Keeping communication public means everybody can benefit and learn from the conversation.