@@ -4,12 +4,12 @@ GraphQL is still an evolving language. This repository contains the
4
4
specification text as well as Pull Requests with suggested improvements and
5
5
contributions.
6
6
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
8
8
improve legibility, fix editorial errors, clear up ambiguity and improve
9
9
examples are encouraged and are often merged by a spec editor with
10
10
little process.
11
11
12
- However, contributions which do meaningfully change the interpretation of the
12
+ However, contributions that _ do _ meaningfully change the interpretation of the
13
13
spec must follow an RFC (Request For Comments) process led by a * champion*
14
14
through a series of * stages* intended to improve * visibility* , allow for
15
15
* 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
35
35
has experience being implemented in a GraphQL library.
36
36
37
37
To 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* .
41
41
42
42
43
43
## Guiding Principles
@@ -56,9 +56,9 @@ move forward. See editor Lee Byron talk about
56
56
57
57
* ** Performance is a feature**
58
58
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 .
62
62
63
63
* ** Favor no change**
64
64
@@ -70,21 +70,21 @@ move forward. See editor Lee Byron talk about
70
70
* ** Enable new capabilities motivated by real use cases**
71
71
72
72
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
75
75
a different way to reach an already achievable outcome.
76
76
77
77
* ** Simplicity and consistency over expressiveness and terseness**
78
78
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.
83
83
84
84
* ** Preserve option value**
85
85
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
88
88
unintuitive: spec rules often begin more strict than necessary with a future
89
89
option to loosen when motivated by a real use case.
90
90
@@ -113,9 +113,9 @@ be *rejected*.
113
113
RFCs are guided by a * champion* through a series of stages: * strawman* ,
114
114
* proposal* , * draft* , and * accepted* (or * rejected* ), each of which has suggested
115
115
entrance 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
117
117
advancements 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
119
119
occur on GitHub.
120
120
121
121
In 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*.
126
126
127
127
## Stage 0: * Strawman*
128
128
129
- A RFC at the * strawman* stage captures a described problem or
129
+ An RFC at the * strawman* stage captures a described problem or
130
130
partially-considered solutions. A * strawman* does not need to meet any entrance
131
131
criteria. A * strawman's* goal is to prove or disprove a problem and guide
132
132
discussion towards either rejection or a preferred solution. A * strawman* may
@@ -147,8 +147,8 @@ criteria for *proposal*.
147
147
## Stage 1: * Proposal*
148
148
149
149
An 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
152
152
both the problem and the solution via examples and spec edits. A * proposal*
153
153
should be a pull request.
154
154
@@ -177,9 +177,9 @@ libraries *may* implement *proposals*, though are encouraged to not enable the
177
177
## Stage 2: * Draft*
178
178
179
179
An 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*
183
183
must be a pull request.
184
184
185
185
* Entrance criteria:*
@@ -215,22 +215,23 @@ implemented in GraphQL.js.
215
215
* Complete spec edits, including examples and prose
216
216
* Compliant implementation in GraphQL.js (fully tested and merged or ready to merge)
217
217
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.
224
225
225
226
An * accepted* RFC is merged into the GraphQL spec's master branch by an editor
226
227
and will be included in the next released revision.
227
228
228
229
229
230
## Stage X: * Rejected*
230
231
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* .
234
235
A * proposal* may become * rejected* for similar reasons as well as if it fails to
235
236
reach consensus or loses the confidence of its * champion* . Likewise a * draft*
236
237
may encounter unforeseen issues during implementations which cause it to lose
0 commit comments