Merge pull request #223 from joshtriplett/api-change-proposal-templat…

…e-changes

Updates to the API Change Proposal template

.github/ISSUE_TEMPLATE/api-change-proposal.md

@@ -10,19 +10,31 @@ assignees: ""
 
 ## Problem statement
 
-<!-- Start with a concise description of the problem(s) this API change proposal is trying to solve. -->
+<!-- Start with a concise description of the problem you're trying to solve. Don't talk about possible solutions yet. -->
 
-## Motivation, use-cases
+## Motivating examples or use cases
 
-<!-- Next add any motivating examples. Examples should ideally be real world examples or minimized versions of the real world example in scenarios where the motivating code is not open source. -->
+<!-- Next add any motivating examples. Examples should ideally be real world examples, or minimized versions of the real world example in scenarios where the motivating code is not open source. -->
 
-## Solution sketches
+## Solution sketch
 
-<!-- Please also sketch out one or more solutions to the problem. For alternative solutions please also include any reasoning for why you didn't suggest those as the primary solution. You don't have to have all the details worked out, but it should be enough to convey the idea. -->
+<!--
+If you have a sketch of a concrete solution, please include it here. You don't have to have all the details worked out, but it should be enough to convey the idea.
+
+If you want to smoke-test whether some solution to the problem would be acceptable, you can delete this section.
+-->
+
+## Alternatives
+
+<!--
+Please also discuss alternative solutions to the problem. Include any reasoning for why you didn't suggest those as the primary solution.
+
+Could this be written using existing APIs? If so, roughly what would that look like? Why does it need to be different? Could this be done as a crate on crates.io?
+-->
 
 ## Links and related work
 
-<!-- Provide links to any internal thread(s), github issues, related work from other languages, or other things that are worth following up on. -->
+<!-- Provide links to any <https://internals.rust-lang.org> thread(s), github issues, approaches to this problem in other languages/libraries, or similar supporting information. -->
 
 ## What happens now?