Update contributing guide; tweak pull request template (#7317)

* Update contributing guide; tweak pull request template

* Update .github/CONTRIBUTING.md

Co-Authored-By: Stephane Delcroix <stephane@delcroix.org>

.github/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thanks you for your interest in contributing to Xamarin.Forms! In this document we'll outline what you need to know about contributing and how to get started.
+Thank you for your interest in contributing to Xamarin.Forms! In this document, we'll outline what you need to know about contributing and how to get started.
 
 ## Code of Conduct
 
@@ -8,56 +8,68 @@ Please see our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Prerequisite
 
-You will need to complete a Contribution License Agreement before any pull request can be accepted. Review the CLA at https://cla.dotnetfoundation.org/. When you submit a pull request, a CLA assistant bot will confirm you have completed the agreement, or provide you with an opportunitiy to do so.
+You will need to complete a Contribution License Agreement before any pull request can be accepted. Review the CLA at https://cla.dotnetfoundation.org/. When you submit a pull request, a CLA assistant bot will confirm you have completed the agreement, or provide you with an opportunity to do so.
 
 ## Contributing Code
 
 Check out [A Beginner's Guide for Contributing to Xamarin.Forms](https://devblogs.microsoft.com/xamarin/beginners-guide-contributing-xamarin-forms/).
 
-### Bug Fixes
+### What to work on
 
-If you're looking for something to fix, please browse [open issues](https://github.com/xamarin/Xamarin.Forms/issues). Check for issues tagged <a href="https://github.com/xamarin/Xamarin.Forms/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22" class="label v-align-text-top labelstyle-159818 linked-labelstyle-159818" data-ga-click="Maintainer label education banner, dismiss, repository_nwo:xamarin/Xamarin.Forms; context:issues; label_name:help wanted; public:true; repo_has_help_wanted_label:true; repo_has_good_first_issue_label:false; shows_go_to_labels:true" data-octo-click="maintainer_label_education" data-octo-dimensions="action:click_label,actor_id:41873,user_id:790012,repository_id:54213490,repository_nwo:xamarin/Xamarin.Forms,context:issues,label_name:help wanted,public:true,repo_has_help_wanted_label:true,repo_has_good_first_issue_label:false,shows_go_to_labels:true" style="background-color: #159818; color: #fff" title="Label: help wanted">help wanted</a> and <a href="https://github.com/xamarin/Xamarin.Forms/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22" class="label v-align-text-top labelstyle-7057ff linked-labelstyle-7057ff" data-ga-click="Maintainer label education banner, dismiss, repository_nwo:xamarin/Xamarin.Forms; context:issues; label_name:good first issue; public:true; repo_has_help_wanted_label:true; repo_has_good_first_issue_label:false; shows_go_to_labels:true" data-octo-click="maintainer_label_education" data-octo-dimensions="action:click_label,actor_id:41873,user_id:790012,repository_id:54213490,repository_nwo:xamarin/Xamarin.Forms,context:issues,label_name:good first issue,public:true,repo_has_help_wanted_label:true,repo_has_good_first_issue_label:false,shows_go_to_labels:true" style="background-color: #7057ff; color: #fff" title="Label: good first issue">good first issue</a>.
+If you're looking for something to work on, please browse [open issues](https://github.com/xamarin/Xamarin.Forms/issues). Any issue that is not already assigned is up for grabs. You can also look for issues tagged <a href="https://github.com/xamarin/Xamarin.Forms/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22" class="label v-align-text-top labelstyle-159818 linked-labelstyle-159818" data-ga-click="Maintainer label education banner, dismiss, repository_nwo:xamarin/Xamarin.Forms; context:issues; label_name:help wanted; public:true; repo_has_help_wanted_label:true; repo_has_good_first_issue_label:false; shows_go_to_labels:true" data-octo-click="maintainer_label_education" data-octo-dimensions="action:click_label,actor_id:41873,user_id:790012,repository_id:54213490,repository_nwo:xamarin/Xamarin.Forms,context:issues,label_name:help wanted,public:true,repo_has_help_wanted_label:true,repo_has_good_first_issue_label:false,shows_go_to_labels:true" style="background-color: #159818; color: #fff" title="Label: help wanted">help wanted</a> and <a href="https://github.com/xamarin/Xamarin.Forms/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22" class="label v-align-text-top labelstyle-7057ff linked-labelstyle-7057ff" data-ga-click="Maintainer label education banner, dismiss, repository_nwo:xamarin/Xamarin.Forms; context:issues; label_name:good first issue; public:true; repo_has_help_wanted_label:true; repo_has_good_first_issue_label:false; shows_go_to_labels:true" data-octo-click="maintainer_label_education" data-octo-dimensions="action:click_label,actor_id:41873,user_id:790012,repository_id:54213490,repository_nwo:xamarin/Xamarin.Forms,context:issues,label_name:good first issue,public:true,repo_has_help_wanted_label:true,repo_has_good_first_issue_label:false,shows_go_to_labels:true" style="background-color: #7057ff; color: #fff" title="Label: good first issue">good first issue</a>. Before you select an enhancement to work on, see Status of Proposals below. Make sure you're working on something in the Ready For Implementation category!
 
 Follow the style used by the [.NET Foundation](https://github.com/dotnet/corefx/blob/master/Documentation/coding-guidelines/coding-style.md), with two primary exceptions:
 
-- We do not use the `private` keyword as it is the default accessibility level in C#.
-- We use hard tabs over spaces. You can change this setting in VS 2015 via `Tools > Options` and navigating to `Text Editor > C#` and selecting the "Keep tabs" radio option.
+- We do not use the `private` keyword, as it is the default accessibility level in C#.
+- We use hard tabs over spaces.
 
-Read and follow our [Pull Request template](https://github.com/xamarin/Xamarin.Forms/blob/master/PULL_REQUEST_TEMPLATE.md)
+Read and follow our [Pull Request template](https://github.com/xamarin/Xamarin.Forms/blob/master/PULL_REQUEST_TEMPLATE.md).
 
-### Proposals
+### Pull Request Requirements
 
-To propose a change or new feature, review the guidance below and then [open an issue using this template](https://github.com/xamarin/Xamarin.Forms/issues/new?labels=enhancement,proposal-open&body=%23%23Summary%0APlease%20provide%20a%20brief%20summary%20of%20your%20proposal.%20Two%20to%20three%20sentences%20is%20best%20here.%0A%0A%23%23API%20Changes%0A%0AInclude%20a%20list%20of%20all%20API%20changes%2C%20additions%2C%20subtractions%20as%20would%20be%20required%20by%20your%20proposal.%20These%20APIs%20should%20be%20considered%20placeholders%2C%20so%20the%20naming%20is%20not%20as%20important%20as%20getting%20the%20concepts%20correct.%20If%20possible%20you%20should%20include%20some%20%22example%22%20code%20of%20usage%20of%20your%20new%20API.%0A%0Ae.g.%0A%0AIn%20order%20to%20facilitate%20the%20new%20Shiny%20Button%20api%2C%20a%20bool%20is%20added%20to%20the%20Button%20class.%20This%20is%20done%20as%20a%20bool%20because%20it%20is%20simpler%20to%20data%20bind%20and%20other%20reasons...%0A%0A%20%20%20%20var%20button%20%3D%20new%20Button%20()%3B%0A%20%20%20%20button.MakeShiny%20%3D%20true%3B%20%2F%2F%20new%20API%0A%0AThe%20MakeShiny%20API%20works%20even%20if%20the%20button%20is%20already%20visible.%0A%0A%23%23Intended%20Use%20Case%0AProvide%20a%20detailed%20example%20of%20where%20your%20proposal%20would%20be%20used%20and%20for%20what%20purpose.).
+ We use red-green-refactor test driven development. If you're planning to work on a bug fix, please be sure to create a test case in the UI tests suite (or unit tests, if you're working on Core/XAML code) that proves that the behavior is broken and then proves that the behavior was resolved after your changes. If at all possible, the test should be automated. If the test cannot be automated, then it should include manual testing instructions on screen.
 
-#### Non-Starter Topics
-The following topics should generally not be proposed for discussion as they are non-starters:
+## Proposals/Enhancements/Suggestions
 
-* Port to WPF/UWP naming
-* Large renames of APIs
-* Large non-backward-compatible breaking changes
-* Platform-Specifics which can be accomplished without changing Xamarin.Forms.Core
-* Avoid clutter posts like "+1" which do not serve to further the conversation
+To propose a change or new feature, open an issue using the [Feature request template](https://github.com/xamarin/Xamarin.Forms/issues/new?assignees=&labels=proposal-open%2C+t%2Fenhancement+%E2%9E%95&template=feature_request.md&title=%5BEnhancement%5D+YOUR+IDEA%21). You may also use the [Spec template](https://github.com/xamarin/Xamarin.Forms/issues/new?assignees=&labels=proposal-open%2C+t%2Fenhancement+%E2%9E%95&template=spec.md&title=%5BSpec%5D++) if you have an idea of what the API should look like.
 
-#### Proposal States
-##### Open
-Open proposals are still under discussion. Please leave your concrete, constructive feedback on this proposal. +1s and other clutter posts which do not add to the discussion will be removed.
+### Status of Proposals
 
-##### Accepted
-Accepted proposals are proposals that both the community and core Xamarin.Forms agree should be a part of Xamarin.Forms. These proposals are ready for implementation, but do not yet have a developer actively working on them. These proposals are available for anyone to work on, both community and the core Xamarin.Forms team.
+Proposals (also called Enhancements or Suggestions) will start out in the [Enhancements project](https://github.com/xamarin/Xamarin.Forms/projects/5) and will be sorted into columns based on their current status.
 
-If you wish to start working on an accepted proposal, please reply to the thread so we can mark you as the implementor and change the title to In Progress. This helps to avoid multiple people working on the same thing. If you decide to work on this proposal publicly, feel free to post a link to the branch as well for folks to follow along.
+#### Under consideration
+This issue is proposed to the community for further support or ideas. Make your votes, voice your opinions, and help develop a specification that someone can work from. A proposal in this column is likely not ready to be worked on yet.
 
-###### What "Accepted" does mean
-* Any community member is welcome to work on the idea.
-* The core Xamarin.Forms team _may_ consider working on this idea on their own, but has not done so until it is marked "In Progress" with a team member assigned as the implementor.
-* Any pull request implementing the proposal will be welcomed with an API and code review.
+#### Discussion Required
+Similar to "Under consideration", except there are clear reasons or concerns about adding this to the platform. This is not quite a rejected state, but this issue requires a lot of problem solving before it should be worked on.
 
-###### What "Accepted" does not mean
-* The proposal will ever be implemented, either by a community member or by the core Xamarin.Forms team.
-* The core Xamarin.Forms team is committing to implementing a proposal, even if nobody else does. Accepted proposals simply mean that the core Xamarin.Forms team and the community agree that this proposal should be a part of Xamarin.Forms.
+#### Needs Specification
+This idea is accepted to be added to Xamarin.Forms. However, it can't be worked on until it has a clear specification, including API changes, sample use cases, etc. See the [Spec template](https://github.com/xamarin/Xamarin.Forms/issues/new?assignees=&labels=proposal-open%2C+t%2Fenhancement+%E2%9E%95&template=spec.md&title=%5BSpec%5D++) for the type of information that is needed.
 
-##### In Progress
-Once a developer has begun work on a proposal, either from the core Xamarin.Forms team or a community member, the proposal is marked as in progress with the implementors name and (possibly) a link to a development branch to follow along with progress.
+#### Needs Design Review
+The specification is written for this accepted proposal, and now we need to review it to make sure that it is easy to use, extensible, etc.
 
-#### Rejected
-Rejected proposals will not be implemented or merged into Xamarin.Forms. Once a proposal is rejected, the thread will be closed and the conversation is considered completed, pending considerable new information or changes..
+#### Ready for Implementation
+Issues in this column should be ready to implement; all of the required information should be in the issue at this point. Unless the issue has an assignee already, anyone is welcome to pick something from this column!
+
+#### In Progress
+Issues that have a matching PR are automatically removed from this project entirely; however, if someone wants to claim an issue and submit a PR later, the issue should be moved to this column so someone else doesn't start working on it at the same time.
+
+#### External
+These issues won't involve code that is in the Xamarin.Forms repository, but for one reason or another, it is still tracked here.
+
+#### Closed
+Proposals that were closed without being implemented.
+
+## Review Process
+All pull requests need to be reviewed and tested by at least two members of the Xamarin.Forms team. We do our best to review pull requests in a timely manner, but please be patient! Two reviewers will be assigned and will start the review process as soon as possible. If there are any changes requested, the contributor should make them at their earliest convenience or let the reviewers know that they are unable to make further contributions. If the pull request requires only minor changes, then someone else may pick it up and finish it. We will do our best to make sure that all credit is retained for contributors. 
+
+Once a pull request has two approvals, it will receive an "approved" label. As long as no UI or unit tests are failing, this pull request can be merged at this time.
+
+## Merge Process
+Bug fixes should be targeted at the earliest appropriate branch.
+- The _current stable branch_ corresponds to the latest stable version available on NuGet.org. This branch will now only accept regressions or fixes that meet a very high bar and low risk.
+- The _current prerelease branch_ corresponds to the latest prerelease version available on NuGet.org. This branch will only accept bug fixes without API changes or breaking changes, with the exception of any API that is under an experimental flag.
+- _Master_ corresponds to a version that is not yet tagged. This is also the "nightly" branch. This is where anything that doesn't fit into the stable or prerelease branches should be targeted.
+
+Commits will be merged up from stable to prerelease to master branches on a regular basis (typically every Monday and whenever a new release is tagged).

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,14 @@
+<!-- WAIT! Before you submit this PR, make sure you're building on and targeting the right branch!
+     - If this is an enhancement or contains API changes or breaking changes, target master.
+     - If the issue you're working on has a milestone, target the corresponding branch.
+     - If this is a bug fix, target the branch of the latest stable version (unless the bug is only in a prerelease or master, of course!).
+     See [Contributing](https://github.com/xamarin/Xamarin.Forms/blob/master/CONTRIBUTING.md) for more tips!
+
+     PLEASE DELETE THE ALL THESE COMMENTS BEFORE SUBMITTING! THANKS!!!
+ -->
 ### Description of Change ###
 
-<!-- Describe your changes here. -->
+<!-- Describe your changes here. If you're fixing a regression, please also include a link to the commit that first introduced this issue, if possible. -->
 
 ### Issues Resolved ### 
 <!-- Please use the format "fixes #xxxx" for each issue this PR addresses -->
@@ -11,15 +19,14 @@
 <!-- List all API changes here (or just put None), example:
 
 Added:
- - string ListView.GroupName { get; set; } //Bindable Property
- - int ListView.GroupId { get; set; } // Bindable Property
- - void ListView.Clear ();
+ - bool FakeControl.MakeShiny { get; set; } //Bindable Property
+ - void FakeControl.Clear ();
 
 Changed:
- - object ListView.SelectedItem => Cell ListView.SelectedItem
+ - object FakeControl.MakeShiny => FakeControl FakeControl.MakeShiny
  
  Removed:
- - object ListView.SelectedItem => Cell ListView.SelectedItem
+ - object FakeControl.MakeShiny => FakeControl FakeControl.MakeShiny
  
  -->
  
@@ -47,7 +54,7 @@ Not applicable
 <!-- Please list the steps that should be taken to properly test these changes on each relevant platform. If you were unable to test these changes yourself on any or all platforms, please let us know. Also, if you are able to attach a video of your test run, you will be our personal hero. -->
 
 ### PR Checklist ###
+<!-- To be completed by reviewers -->
 
-- [ ] Has automated tests <!-- (if tests are omitted or manual, state reason in description) -->
-- [ ] Rebased on top of the target branch at time of PR
-- [ ] Changes adhere to coding standard
+- [ ] Targets the correct branch
+- [ ] Tests are passing (or failures are unrelated)