Revamp Contributing and add GH templates (#519)

* Revamp Contributing and add GH templates

This is a top-to-bottom revamp of the Contributing.md document which includes a more thorough and implementable process for identifying what stage a PR is in and what is expected to reach the next stage. It also captures the guiding principles for spec improvements.

* Improve intro paragraphs

* Improve templates

Author: leebyron

CONTRIBUTING.md

@@ -1,80 +1,239 @@
-# Stages for changes to the GraphQL Specification
+# GraphQL Specification Contribution Guide
 
-> **Document status:** [Draft](https://github.com/facebook/graphql/pull/342)
+GraphQL is still an evolving language. This repository contains the
+specification text as well as Pull Requests with suggested improvements and
+contibutions.
 
-This document describes the stages required for merging changes to the
-GraphQL Specification. These stages are intended to:
+Contributions which do not change the interpretation of the spec but instead
+improve legibility, fix editorial errors, clear up ambiguity and improve
+examples are encouraged and are often merged by a spec editor with
+little process.
 
-+ Be as flexible as possible.
-+ Define a clear process for getting changes into the specification.
-+ Provide visibility for participants in the GraphQL ecosystem into the
-status and progress of proposals.
-+ Encourage community discussion around the proposed changes.
+However, contributions which do meaningfully change the interpretation of the
+spec must follow an RFC (Request For Comments) process led by a *champion*
+through a series of *stages* intended to improve *visibility*, allow for
+*discussion* to reach the best solution, and arrive at *consensus*. This process
+becomes ever more important as GraphQL's community broadens.
 
-Any changes to the specification that affect the behavior of **GraphQL server
-or client implementations** should go through the stages below no matter how
-small they are. All other changes should be labeled as “editorial” and may
-be merged right away.  Also, please read the [Code of Conduct](CODE_OF_CONDUCT.md)
-to know what is expected when making contributions to this project.
+When proposing or weighing-in on any issue or pull request, consider the
+[Code of Conduct](CODE_OF_CONDUCT.md) to better understand expected and
+unacceptable behavior.
 
-## Stage -2: proposed change (optional)
 
-**Prerequisite**: Described problem/change should be specific to the content of
-GraphQL Specification and not be an implementation detail.
+## Contributing to GraphQL Libraries
 
-**Purpose**: Filter out questions and issues for other repos, and engage community
-discussion.
+A common point of confusion for those who wish to contribute to GraphQL is where
+to start. In fact, you may have found yourself here after attempting to make an
+improvement to a GraphQL library. Should a new addition be made to the GraphQL
+spec first or a GraphQL library first? Admittedly, this can become a bit of a
+[chicken-or-egg](https://en.wikipedia.org/wiki/Chicken_or_the_egg) dilemma.
 
-## Stage -1: PR requested (optional)
+GraphQL libraries seek to be "spec compliant", which means they discourage
+changes that cause them to behave differently from the spec as written. However,
+they also encourage pull requests for changes that accompany an RFC *proposal*
+or RFC *draft*. In fact, a spec contribution RFC won't be *accepted* until it
+has experience being implemented in a GraphQL library.
 
-**Prerequisite**: Issue should contain description of problem or use case and
-proposed solution.
+To allow a library to remain spec compliant while also implementing *proposals*
+and *drafts*, it may request that these features are built so they are disabled
+by default with opt-in option flags or it may simply wait to merge a well-tested
+pull request until the spec proposal is *accepted*.
 
-**Purpose**: Find member of community to be champion for this change.
 
-## Stage 0: Proposal
+## Guiding Principles
 
-**Prerequisite**:
-+ Initial version of spec changes.
-+ Filled checklist ([TBD](https://youtu.be/mePT9MNTM98?t=20m32s)) in PR description.
+GraphQL's evolution is guided by a few principles. Suggested contributions
+should use these principles to guide the details of an RFC and decisions to
+move forward. See editor Lee Byron talk about
+[guiding principles at GraphQL Europe 2017](https://youtu.be/mePT9MNTM98?t=17m9s).
 
-**Steps**: Start review process.
+* **Backwards compatibility**
 
-**Post-Acceptance Changes Expected**: Major.
+  Once a query is written, it should always mean the same thing and return the
+  same shaped result. Future changes should not change the meaning of existing
+  schema or queries or in any other way cause an existing compliant GraphQL
+  service to become non-compliant for prior versions of the spec.
 
-## Stage 1: Draft
+* **Performance is a feature**
 
-**Prerequisite**:
-+ Finalized wording inside specification document.
-+ Proposed spec changes don’t have any blind spots (undescribed edge-cases,
-missed changes to related part of spec, etc).
+  GraphQL typically avoids syntax or behaviors which could place burden on
+  runtime efficiency or make demands of a GraphQL service it cannot
+  efficiently fulfill.
 
-**Steps**: Start working on [graphql-js](https://github.com/graphql/graphql-js)
-PR
+* **Favor no change**
 
-**Post-Acceptance Changes Expected**: Incremental.
+  As GraphQL is implemented in over a dozen languages under the collaboration
+  of hundreds of individuals, incorporating any change has a high cost.
+  Accordingly, proposed changes must meet a very high bar of added value.
+  The burden of proof of value is on the contributor to illustrate this value.
 
-## Stage 2: Candidate
+* **Enable new capabilities motivated by real use cases**
 
-**Prerequisite**:
-+ Prepared PR for graphql-js.
-+ Notify all members of [GraphQL WG](https://github.com/graphql/graphql-wg).
-+ Community consent on the proposed change. If it’s hard to achieve, add it to
-agenda of the next WG meeting.
-+ No changes to the graphql and graphql-js PRs for at least last 7 days.
+  Every change should intend on unlocking a real and reasonable use case. Real
+  examples are always more interesting than theoretical ones, and common
+  scenarios are more interesting than rare ones. RFCs should do more than offer
+  a different way to reach an already achievable outcome.
 
-**Steps**: Merge graphql-js PR and release NPM package
+* **Simplicity and consistency over expressiveness and terseness**
 
-**Post-Acceptance Changes Expected**: Only those deemed critical based on
-implementation experience.
+  There are plenty of behaviors and patterns found in other languages
+  intentionally absent from GraphQL. "Possible but awkward" is often favored
+  over more complex alternatives. Simplicity (e.g. fewer concepts) is
+  more important than expressing more sophisticated ideas or writing less.
 
-## Stage 3: Merged
+* **Preserve option value**
 
-**Prerequisite**:
-+ At least one month since release of the graphql-js with proposed change.
-+ Community consent on proposed change. If it’s hard to achieve add to agenda of
-the next WG meeting..
+  It's hard to know what the future brings, so whenever possible decisions
+  should be made which allow for more options in the future. Sometimes this is
+  unintuitive: spec rules often begin more strict than necessary with a future
+  option to loosen when motivated by a real use case.
 
-**Steps**: Merge PR into “master” branch.
+* **Understandability is just as important as correctness**
 
-**Post-Acceptance Changes Expected**: None.
+  The GraphQL spec, despite describing technical behavior, is intended to be
+  read by people. Use natural tone and include motivation and examples.
+
+
+## RFC Contribution Champions
+
+Contributing to GraphQL requires a lot of dedicated work. To set clear
+expectations and provide accountability, each proposed RFC (request for
+comments) must have a *champion* who is responsible for addressing feedback and
+completing next steps. An RFC may have multiple *champions*. The spec editors
+are not responsible for completing RFCs which lack a *champion* (though an
+editor may be a *champion* for an RFC).
+
+An RFC which does not have a *champion* may not progress through stages, and can
+become stale. Stale proposals may be picked up by a new *champion* or may
+be *rejected*.
+
+
+## RFC Contribution Stages
+
+RFCs are guided by a *champion* through a series of stages: *strawman*,
+*proposal*, *draft*, and *accepted* (or *rejected*), each of which has suggested
+entrance criteria and next steps detailed below. RFCs typically advance one
+stage at a time, however may advance multiple stages at a time. Stage
+advancements typically occur during
+[Working Group](https://github.com/graphql/graphql-wg) meetings, however may
+occur online.
+
+All RFCs start as either a *strawman* or *proposal*.
+
+## Stage 0: *Strawman*
+
+A RFC at the *strawman* stage captures a described problem or
+partially-considered solutions. A *strawman* does not need to meet any entrance
+criteria. A *strawman's* goal is prove or disprove a problem and guide
+discussion towards rejection or a preferred solution. A *strawman* may be an
+issue or a pull request (though an illustrative pull request is preferrable).
+
+*There is no entrance criteria for a Strawman*
+
+As implied by the name [strawman](https://en.wikipedia.org/wiki/Straw_man_proposal),
+the goal at this stage is to knock it down (*reject*) by considering other
+possible related solutions, showing that the motivating problem can be solved
+with no change to the specification, or that it is not aligned with the
+*guiding principles*.
+
+Once determined that the *strawman* is compelling, it should seek the entrance
+criteria for *proposal*.
+
+
+## Stage 1: *Proposal*
+
+An RFC at the *proposal* stage is a solution to a problem with enough fidelity
+to be discussed in detail. It must be backed by a willing *champion*.
+A *proposal*'s goal is to make a compelling case for acceptance by describing
+both the problem and the solution via examples and spec edits. A *proposal*
+should be a pull request.
+
+*Entrance criteria:*
+
+* Identified *champion*
+* Clear explanation of problem and solution
+* Illustrative examples
+* Incomplete spec edits
+* Identification of potential concerns, challenges, and drawbacks
+
+A *proposal* is subject to the same discussion as a *strawman*: ensuring that it
+is well aligned with the *guiding principles*, is a problem worth solving, and
+is the preferred solution to that problem. A *champion* is not expected to have
+confidence in every detail at this stage and should instead focus on identifying
+and resolving issues and edge-cases. To better understand the ramifications of a
+*proposal*, a *champion* is encouraged to implement it in a GraphQL library.
+
+Most *proposals* are expected to evolve or change and may be rejected. Therefore,
+it is unwise to rely on a *proposal* in a production GraphQL service. GraphQL
+libraries *may* implement *proposals*, though are encouraged to not enable the
+*proposal* feature without explicit opt-in.
+
+
+## Stage 2: *Draft*
+
+An RFC at the *draft* stage is a fully formed solution. There is working group
+consensus that the problem identified is worth solving, and this particular
+solution is preferred. A *draft's* goal is to precisely and completely describe
+the solution and resolve any concerns through library implementations. A *draft*
+must be a pull request.
+
+*Entrance criteria*
+
+* Consensus the solution is preferred (typically via Working Group)
+* Resolution of identified concerns and challenges
+* Precisely described with spec edits
+* Compliant implementation in GraphQL.js (via unmerged pull request)
+
+A *proposal* becomes a *draft* when the set of problems or drawbacks have been
+fully considered and accepted or resolved, and the solution is deemed
+desireable. A *draft*'s goal is to complete final spec edits that are ready to
+be merged and implement the *draft* in GraphQL libraries along with tests to
+gain confidence that the spec text is sufficient.
+
+*Drafts* may continue to evolve and change, occasionally dramatically, and are
+not guaranteed to be accepted. Therefore, it is unwise to rely on a *draft* in a
+production GraphQL Service. GraphQL libraries *should* implement *drafts* to
+provide valuable feedback, though are encouraged not to enable the *draft*
+feature without explicit opt-in when possible.
+
+
+## Stage 3: *Accepted*
+
+An RFC at the *accepted* stage is a completed solution. According to a spec
+editor it is ready to be merged as-is into the spec. The RFC is ready to be
+deployed in GraphQL libraries. An *accepted* RFC must be implemented
+in GraphQL.js.
+
+*Entrace criteria*
+
+* Consensus the solution is complete (via editor or working group)
+* Complete spec edits, including examples and prose
+* Compliant implementation in GraphQL.js (fully tested and merged)
+
+A *draft* is *accepted* when it has learned via implementation and tests that it
+appropriately handles all edge cases, that the spec edits do not only precisely
+describe the new syntax and semantics but include motivating prose, examples,
+and include edits to any other affected areas of the spec. Once *accepted*, a
+*champion* should encourage adoption of the RFC by opening issues or pull
+requests on other popular GraphQL libaries.
+
+An *accepted* RFC is merged into the GraphQL spec's master branch by an editor
+and will be included in the next released revision.
+
+
+## Stage X: *Rejected*
+
+An RFC may be *rejected* at any point and for any reason. Most often because a
+*strawman* was proven to be unnecessary, was not aligned with the *guiding
+principles*, or failed to meet the entrance criteria to become a *proposal*.
+A *proposal* may become *rejected* for similar reasons as well as if it fails to
+reach consensus or loses the confidence of its *champion*. Likewise a *draft*
+may encounter unforseen issues during implementions which cause it to lose
+consensus or the confidence of its *champion*.
+
+RFCs which have lost a *champion* will not be *rejected* immediately, but may
+become *rejected* if they fail to attract a new *champion*.
+
+Once *rejected*, an RFC will typically not be reconsidered. Reconsideration is
+possible if a *champion* believes the original reason for rejection no longer
+applies due to new circumstances or new evidence.

ISSUE_TEMPLATE.md

@@ -0,0 +1,11 @@
+!!! IMPORTANT !!!
+
+Before creating your issue:
+
+* Have a question? Find community resources at https://graphql.org/community/
+
+* Find an editing mistake? Create a Pull Request with the edited fix! The Github UI allows you to edit files directly, find the source files at: https://github.com/facebook/graphql/tree/master/spec
+
+* Improvements to documentation? Head over to https://github.com/graphql/graphql.github.io
+
+* Feature request? First read https://github.com/facebook/graphql/blob/master/CONTRIBUTING.md and prefer creating a Pull Request!

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,3 @@
+!!! IMPORTANT !!!
+
+Please Read https://github.com/facebook/graphql/blob/master/CONTRIBUTING.md before creating a Pull Request.