@@ -4,12 +4,12 @@ GraphQL is still an evolving language. This repository contains the
44specification text as well as Pull Requests with suggested improvements and
55contributions.
66
7- Contributions which do not change the interpretation of the spec but instead
7+ Contributions that do not change the interpretation of the spec but instead
88improve legibility, fix editorial errors, clear up ambiguity and improve
99examples are encouraged and are often merged by a spec editor with
1010little process.
1111
12- However, contributions which do meaningfully change the interpretation of the
12+ However, contributions that _ do _ meaningfully change the interpretation of the
1313spec must follow an RFC (Request For Comments) process led by a * champion*
1414through a series of * stages* intended to improve * visibility* , allow for
1515* discussion* to reach the best solution, and arrive at * consensus* . This process
@@ -35,9 +35,9 @@ or RFC *draft*. In fact, a spec contribution RFC won't be *accepted* until it
3535has experience being implemented in a GraphQL library.
3636
3737To allow a library to remain spec compliant while also implementing * proposals*
38- and * drafts* , it may request that these features are built so they are disabled
39- by default with opt-in option flags or it may simply wait to merge a well-tested
40- pull request until the spec proposal is * accepted* .
38+ and * drafts* , the library's maintainers may request that these new features are
39+ disabled by default with opt-in option flags or they may simply wait to merge a
40+ well-tested pull request until the spec proposal is * accepted* .
4141
4242
4343## Guiding Principles
@@ -56,9 +56,9 @@ move forward. See editor Lee Byron talk about
5656
5757* ** Performance is a feature**
5858
59- GraphQL typically avoids syntax or behaviors which could place burden on
60- runtime efficiency or make demands of a GraphQL service it cannot
61- efficiently fulfill .
59+ GraphQL typically avoids syntax or behaviors that could jeopardize runtime
60+ efficiency, or that make demands of GraphQL services which cannot efficiently
61+ be fulfilled .
6262
6363* ** Favor no change**
6464
@@ -70,21 +70,21 @@ move forward. See editor Lee Byron talk about
7070* ** Enable new capabilities motivated by real use cases**
7171
7272 Every change should intend on unlocking a real and reasonable use case. Real
73- examples are always more interesting than theoretical ones, and common
74- scenarios are more interesting than rare ones. RFCs should do more than offer
73+ examples are always more compelling than theoretical ones, and common
74+ scenarios are more compelling than rare ones. RFCs should do more than offer
7575 a different way to reach an already achievable outcome.
7676
7777* ** Simplicity and consistency over expressiveness and terseness**
7878
79- There are plenty of behaviors and patterns found in other languages
80- intentionally absent from GraphQL. "Possible but awkward" is often favored
81- over more complex alternatives. Simplicity (e.g. fewer concepts) is
82- more important than expressing more sophisticated ideas or writing less.
79+ Plenty of behaviors and patterns found in other languages are intentionally
80+ absent from GraphQL. "Possible but awkward" is often favored over more complex
81+ alternatives. Simplicity (e.g. fewer concepts) is more important than
82+ expressing more sophisticated ideas or writing less.
8383
8484* ** Preserve option value**
8585
86- It's hard to know what the future brings, so whenever possible decisions
87- should be made which allow for more options in the future. Sometimes this is
86+ It's hard to know what the future brings; whenever possible, decisions should
87+ be made that allow for more options in the future. Sometimes this is
8888 unintuitive: spec rules often begin more strict than necessary with a future
8989 option to loosen when motivated by a real use case.
9090
@@ -113,9 +113,9 @@ be *rejected*.
113113RFCs are guided by a * champion* through a series of stages: * strawman* ,
114114* proposal* , * draft* , and * accepted* (or * rejected* ), each of which has suggested
115115entrance criteria and next steps detailed below. RFCs typically advance one
116- stage at a time, however may advance multiple stages at a time. Stage
116+ stage at a time, but may advance multiple stages at a time. Stage
117117advancements typically occur during
118- [ Working Group] ( https://github.com/graphql/graphql-wg ) meetings, however may
118+ [ Working Group] ( https://github.com/graphql/graphql-wg ) meetings, but may also
119119occur on GitHub.
120120
121121In general, it's preferable to start with a pull request so that we can best
@@ -126,7 +126,7 @@ All RFCs start as either a *strawman* or *proposal*.
126126
127127## Stage 0: * Strawman*
128128
129- A RFC at the * strawman* stage captures a described problem or
129+ An RFC at the * strawman* stage captures a described problem or
130130partially-considered solutions. A * strawman* does not need to meet any entrance
131131criteria. A * strawman's* goal is to prove or disprove a problem and guide
132132discussion towards either rejection or a preferred solution. A * strawman* may
@@ -147,8 +147,8 @@ criteria for *proposal*.
147147## Stage 1: * Proposal*
148148
149149An RFC at the * proposal* stage is a solution to a problem with enough fidelity
150- to be discussed in detail. It must be backed by a willing * champion* .
151- A * proposal* 's goal is to make a compelling case for acceptance by describing
150+ to be discussed in detail. It must be backed by a willing * champion* . A
151+ * proposal* 's goal is to make a compelling case for acceptance by describing
152152both the problem and the solution via examples and spec edits. A * proposal*
153153should be a pull request.
154154
@@ -177,9 +177,9 @@ libraries *may* implement *proposals*, though are encouraged to not enable the
177177## Stage 2: * Draft*
178178
179179An RFC at the * draft* stage is a fully formed solution. There is working group
180- consensus that the problem identified should be solved, and this particular
181- solution is preferred. A * draft's* goal is to precisely and completely describe
182- the solution and resolve any concerns through library implementations. A * draft*
180+ consensus the problem identified should be solved, and this particular solution
181+ is preferred. A * draft's* goal is to precisely and completely describe the
182+ solution and resolve any concerns through library implementations. A * draft*
183183must be a pull request.
184184
185185* Entrance criteria:*
@@ -215,22 +215,23 @@ implemented in GraphQL.js.
215215* Complete spec edits, including examples and prose
216216* Compliant implementation in GraphQL.js (fully tested and merged or ready to merge)
217217
218- A * draft* is * accepted* when it has learned via implementation and tests that it
219- appropriately handles all edge cases, that the spec edits do not only precisely
220- describe the new syntax and semantics but include motivating prose, examples,
221- and include edits to any other affected areas of the spec. Once * accepted* , a
222- * champion* should encourage adoption of the RFC by opening issues or pull
223- requests on other popular GraphQL libraries.
218+ A * draft* is * accepted* when the working group or editor has been convinced via
219+ implementations and tests that it appropriately handles all edge cases; that the
220+ spec changes not only precisely describe the new syntax and semantics but
221+ include sufficient motivating prose and examples; and that the RFC includes
222+ edits to any other affected areas of the spec. Once * accepted* , its * champion*
223+ should encourage adoption of the RFC by opening issues or pull requests on other
224+ popular GraphQL libraries.
224225
225226An * accepted* RFC is merged into the GraphQL spec's master branch by an editor
226227and will be included in the next released revision.
227228
228229
229230## Stage X: * Rejected*
230231
231- An RFC may be * rejected* at any point and for any reason. Most often because a
232- * strawman* was proven to be unnecessary, was not aligned with the * guiding
233- principles* , or failed to meet the entrance criteria to become a * proposal* .
232+ An RFC may be * rejected* at any point and for any reason. Most rejections occur
233+ when a * strawman* is proven to be unnecessary, is misaligned with the * guiding
234+ principles* , or fails to meet the entrance criteria to become a * proposal* .
234235A * proposal* may become * rejected* for similar reasons as well as if it fails to
235236reach consensus or loses the confidence of its * champion* . Likewise a * draft*
236237may encounter unforeseen issues during implementations which cause it to lose
0 commit comments