From 72469f06e8cbb81599c0bb7f2c1dc89dc6346197 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Cornell=C3=A0?= Date: Thu, 17 Jul 2014 13:46:06 +0200 Subject: [PATCH 1/7] Add CONTRIBUTING.md file general structure --- CONTRIBUTING.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5d257e25 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# CONTRIBUTING GUIDELINES + +1. [Use the search Luke](#use-the-search-luke) +2. [You have a problem](#you-have-a-problem) +3. [You have a solution](#you-have-a-solution) + +**BONUS:** [You have spare time to volunteer](#you-have-spare-time-to-volunteer) + + +## USE THE SEARCH LUKE + +> May the Force (of past experiences) be with you. + +Trust me, that works 90% of the time. + +You can also take a look at the [FAQ](https://github.com/robbyrussell/oh-my-zsh/wiki/FAQ) +to be sure it hasn't already come up. + +If all fails, your thing hasn't probably been reported yet, so you can go ahead +and read on to the next section. + + +## YOU HAVE A PROBLEM + +See [point 1](#use-the-search-luke). + +If the problem is already reported, comment on the issue so we can know there's +more people with the problem. + +If not, look at the [Troubleshooting](https://github.com/robbyrussell/oh-my-zsh/wiki/Troubleshooting) +page for instructions on how to gather data to better debug your problem. + +Then, you can go ahead and submit an issue with as much detail as you can provide. +We'll do our very best to help you. + +*TODO: fill later* + + +## YOU HAVE A SOLUTION + +See [point 1](#use-the-search-luke). + +If the solution is already reported, try it out and +1 the pull request if the +solution works ok. On the other hand, if you think your solution is better, post +it so we can have both solutions to compare. + +If not, then go ahead and submit a PR. +**Unless your solution is yet another [theme](https://github.com/robbyrussell/oh-my-zsh/wiki/Themes#dont-send-us-your-theme-for-now).** + +*TODO: fill later* + + +---- + +### YOU HAVE SPARE TIME TO VOLUNTEER + +Very nice!! :) + +Please have a look at the [Volunteer](https://github.com/robbyrussell/oh-my-zsh/wiki/Volunteers) +page for instructions on where to start and more. From 9e839ab9c018394f686c62f778bf2a19d3c31b92 Mon Sep 17 00:00:00 2001 From: ncanceill Date: Tue, 5 May 2015 15:39:02 +0200 Subject: [PATCH 2/7] rewrite of contribution guidelines --- CONTRIBUTING.md | 115 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 88 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5d257e25..d7318709 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,58 +1,119 @@ # CONTRIBUTING GUIDELINES -1. [Use the search Luke](#use-the-search-luke) -2. [You have a problem](#you-have-a-problem) -3. [You have a solution](#you-have-a-solution) +Oh-My-Zsh is a community-driven project. Contribution is welcome, encouraged and appreciated. +It is also essential for the development of the project. -**BONUS:** [You have spare time to volunteer](#you-have-spare-time-to-volunteer) +These guidelines are an attempt at better addressing the brobdingnagian amount of pending +issues and pull requests. Please read them closely. +Foremost, be so kind as to [search](#use-the-search-luke), thus ensuring any contribution +you would make is not already covered. -## USE THE SEARCH LUKE +* [Issues](#reporting-issues) + * [You have a problem](#you-have-a-problem) + * [You have a suggestion](#you-have-a-suggestion) +* [Pull Requests](#submitting-pull-requests) + * [Getting started](#getting-started) + * [You have a solution](#you-have-a-solution) + * [You have an addition](#you-have-an-addition) +* [Information sources (_aka_ search)](#use-the-search-luke) -> May the Force (of past experiences) be with you. +**BONUS:** [Volunteering](#you-have-spare-time-to-volunteer) -Trust me, that works 90% of the time. +## Reporting Issues -You can also take a look at the [FAQ](https://github.com/robbyrussell/oh-my-zsh/wiki/FAQ) -to be sure it hasn't already come up. +### You have a problem -If all fails, your thing hasn't probably been reported yet, so you can go ahead -and read on to the next section. +Please be so kind as to [search](#use-the-search-luke) for any open issue already covering +your problem. - -## YOU HAVE A PROBLEM - -See [point 1](#use-the-search-luke). - -If the problem is already reported, comment on the issue so we can know there's -more people with the problem. +If you find one, comment on it so we can know there are more people experiencing it. If not, look at the [Troubleshooting](https://github.com/robbyrussell/oh-my-zsh/wiki/Troubleshooting) page for instructions on how to gather data to better debug your problem. -Then, you can go ahead and submit an issue with as much detail as you can provide. -We'll do our very best to help you. +Then, you can go ahead and create an issue with as much detail as you can provide. +It should include the data gathered as indicated above, along with: -*TODO: fill later* +1. How to reproduce the problem +2. What the correct behavior should be +3. What the actual behavior is +Please copy to anyone relevant (_eg_ plugin maintainers) by mentioning their GitHub handle +(starting with `@`) in your message. -## YOU HAVE A SOLUTION +We will do our very best to help you. -See [point 1](#use-the-search-luke). +### You have a suggestion + +Please be so kind as to [search](#use-the-search-luke) for any open issue already covering +your suggestion. + +If you find one, comment on it so we can know there are more people supporting it. + +If not, you can go ahead and create an issue. Please copy to anyone relevant (_eg_ plugin +maintainers) by mentioning their GitHub handle (starting with `@`) in your message. + +## Submitting Pull Requests + +### Getting started + +You should be familiar with the basics of +[contributing on GitHub](https://help.github.com/articles/using-pull-requests) and have a fork +[properly set up](https://github.com/robbyrussell/oh-my-zsh/wiki/Contribution-Technical-Practices). + +You MUST always create PRs with _a dedicated branch_ based on the latest upstream tree. + +If you create your own PR, please make sure you do it right. Also be so kind as to reference +any issue that would be solved in the PR description body, +[for instance](https://help.github.com/articles/closing-issues-via-commit-messages/) +_"Fixes #XXXX"_ for issue number XXXX. + +### You have a solution + +Please be so kind as to [search](#use-the-search-luke) for any open issue already covering +your [problem](#you-have-a-problem), and any pending PR covering your solution. If the solution is already reported, try it out and +1 the pull request if the solution works ok. On the other hand, if you think your solution is better, post it so we can have both solutions to compare. -If not, then go ahead and submit a PR. -**Unless your solution is yet another [theme](https://github.com/robbyrussell/oh-my-zsh/wiki/Themes#dont-send-us-your-theme-for-now).** +If not, then go ahead and submit a PR. Please copy to anyone relevant (_eg_ plugin +maintainers) by mentioning their GitHub handle (starting with `@`) in your message. -*TODO: fill later* +### You have an addition +Please [do not](https://github.com/robbyrussell/oh-my-zsh/wiki/Themes#dont-send-us-your-theme-for-now) +send themes for now. + +Please be so kind as to [search](#use-the-search-luke) for any pending PR covering or +related to what you want to add. + +If you find one, try it out and work with the author on a common solution. + +If not, then go ahead and submit a PR. Please copy to anyone relevant (_eg_ plugin +maintainers) by mentioning their GitHub handle (starting with `@`) in your message. ---- -### YOU HAVE SPARE TIME TO VOLUNTEER +## Use the Search, Luke + +> May the Force (of past experiences) be with you + +GitHub offers [many search features](https://help.github.com/articles/searching-github/) +to help you check whether a similar contribution to yours already exists. Please search +before making any contribution, it avoids duplicates and eases maintenance. Trust me, +that works 90% of the time. + +You can also take a look at the [FAQ](https://github.com/robbyrussell/oh-my-zsh/wiki/FAQ) +to be sure your contribution has not already come up. + +If all fails, your thing has probably not been reported yet, so you can go ahead +and [create an issue](#reporting-issues) or [submit a PR](#submitting-pull-requests). + +---- + +### You have spare time to volunteer Very nice!! :) From eb5229d962509cc23296bed08b52a46159da29fd Mon Sep 17 00:00:00 2001 From: Nicolas Canceill Date: Fri, 8 May 2015 11:17:24 +0200 Subject: [PATCH 3/7] Contributing: simple english, formatting --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7318709..827037f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,10 +3,10 @@ Oh-My-Zsh is a community-driven project. Contribution is welcome, encouraged and appreciated. It is also essential for the development of the project. -These guidelines are an attempt at better addressing the brobdingnagian amount of pending +These guidelines are an attempt at better addressing the huge amount of pending issues and pull requests. Please read them closely. -Foremost, be so kind as to [search](#use-the-search-luke), thus ensuring any contribution +Foremost, be so kind as to [search](#use-the-search-luke). This ensures any contribution you would make is not already covered. * [Issues](#reporting-issues) @@ -98,7 +98,7 @@ maintainers) by mentioning their GitHub handle (starting with `@`) in your messa ## Use the Search, Luke -> May the Force (of past experiences) be with you +_May the Force (of past experiences) be with you_ GitHub offers [many search features](https://help.github.com/articles/searching-github/) to help you check whether a similar contribution to yours already exists. Please search From ae31e8e1f84d4358439db1720c4a0d98484282b4 Mon Sep 17 00:00:00 2001 From: ncanceill Date: Fri, 8 May 2015 11:33:02 +0200 Subject: [PATCH 4/7] contributing: mention testing --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 827037f4..cbcd7590 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,6 +94,8 @@ If you find one, try it out and work with the author on a common solution. If not, then go ahead and submit a PR. Please copy to anyone relevant (_eg_ plugin maintainers) by mentioning their GitHub handle (starting with `@`) in your message. +For any extensive change, _eg_ a new plugin, you will have to find testers to +1 your PR. + ---- ## Use the Search, Luke From 5a031ce3e67a0e99b6d043aab6034b0532cec26a Mon Sep 17 00:00:00 2001 From: ncanceill Date: Fri, 16 Oct 2015 23:18:34 +0200 Subject: [PATCH 5/7] contributing: "correct" -> "expected" behavior see https://github.com/robbyrussell/oh-my-zsh/pull/3770#issuecomment-120546525 --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cbcd7590..cd0d625f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ Then, you can go ahead and create an issue with as much detail as you can provid It should include the data gathered as indicated above, along with: 1. How to reproduce the problem -2. What the correct behavior should be +2. What the expected behavior should be 3. What the actual behavior is Please copy to anyone relevant (_eg_ plugin maintainers) by mentioning their GitHub handle From bc2ccdd812cb90d889f14731896c06c3715876a9 Mon Sep 17 00:00:00 2001 From: ncanceill Date: Fri, 16 Oct 2015 23:23:38 +0200 Subject: [PATCH 6/7] contributing: improve PR section --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cd0d625f..f86acd66 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,11 +72,11 @@ _"Fixes #XXXX"_ for issue number XXXX. ### You have a solution Please be so kind as to [search](#use-the-search-luke) for any open issue already covering -your [problem](#you-have-a-problem), and any pending PR covering your solution. +your [problem](#you-have-a-problem), and any pending/merged/rejected PR covering your solution. If the solution is already reported, try it out and +1 the pull request if the solution works ok. On the other hand, if you think your solution is better, post -it so we can have both solutions to compare. +it with a reference to the other one so we can have both solutions to compare. If not, then go ahead and submit a PR. Please copy to anyone relevant (_eg_ plugin maintainers) by mentioning their GitHub handle (starting with `@`) in your message. @@ -86,7 +86,7 @@ maintainers) by mentioning their GitHub handle (starting with `@`) in your messa Please [do not](https://github.com/robbyrussell/oh-my-zsh/wiki/Themes#dont-send-us-your-theme-for-now) send themes for now. -Please be so kind as to [search](#use-the-search-luke) for any pending PR covering or +Please be so kind as to [search](#use-the-search-luke) for any pending/merged/rejected PR covering or related to what you want to add. If you find one, try it out and work with the author on a common solution. From 573df1a8ffa8167e29a8e403a0a0caedac84c972 Mon Sep 17 00:00:00 2001 From: ncanceill Date: Fri, 16 Oct 2015 23:34:34 +0200 Subject: [PATCH 7/7] contributing: "eg" -> "e.g." because oxford see http://www.oxforddictionaries.com/definition/english/e.g. --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f86acd66..c1778704 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,7 +39,7 @@ It should include the data gathered as indicated above, along with: 2. What the expected behavior should be 3. What the actual behavior is -Please copy to anyone relevant (_eg_ plugin maintainers) by mentioning their GitHub handle +Please copy to anyone relevant (e.g. plugin maintainers) by mentioning their GitHub handle (starting with `@`) in your message. We will do our very best to help you. @@ -51,7 +51,7 @@ your suggestion. If you find one, comment on it so we can know there are more people supporting it. -If not, you can go ahead and create an issue. Please copy to anyone relevant (_eg_ plugin +If not, you can go ahead and create an issue. Please copy to anyone relevant (e.g. plugin maintainers) by mentioning their GitHub handle (starting with `@`) in your message. ## Submitting Pull Requests @@ -78,7 +78,7 @@ If the solution is already reported, try it out and +1 the pull request if the solution works ok. On the other hand, if you think your solution is better, post it with a reference to the other one so we can have both solutions to compare. -If not, then go ahead and submit a PR. Please copy to anyone relevant (_eg_ plugin +If not, then go ahead and submit a PR. Please copy to anyone relevant (e.g. plugin maintainers) by mentioning their GitHub handle (starting with `@`) in your message. ### You have an addition @@ -91,10 +91,10 @@ related to what you want to add. If you find one, try it out and work with the author on a common solution. -If not, then go ahead and submit a PR. Please copy to anyone relevant (_eg_ plugin +If not, then go ahead and submit a PR. Please copy to anyone relevant (e.g. plugin maintainers) by mentioning their GitHub handle (starting with `@`) in your message. -For any extensive change, _eg_ a new plugin, you will have to find testers to +1 your PR. +For any extensive change, e.g. a new plugin, you will have to find testers to +1 your PR. ----