Skip to content

Commit d2eb4a8

Browse files
authoredJun 4, 2020
Small fixes and clarifications to contributing (graphql#723)
* Small fixes and clarifications to contributing * Small changes from feedback The removal of several words caused re-wrapping due to line length conventions, so the meaningful diff is much smaller than it looks.
1 parent 6c9e13b commit d2eb4a8

File tree

1 file changed

+34
-33
lines changed

1 file changed

+34
-33
lines changed
 

‎CONTRIBUTING.md

+34-33
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,12 @@ GraphQL is still an evolving language. This repository contains the
44
specification text as well as Pull Requests with suggested improvements and
55
contributions.
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
88
improve legibility, fix editorial errors, clear up ambiguity and improve
99
examples are encouraged and are often merged by a spec editor with
1010
little process.
1111

12-
However, contributions which do meaningfully change the interpretation of the
12+
However, contributions that _do_ meaningfully change the interpretation of the
1313
spec must follow an RFC (Request For Comments) process led by a *champion*
1414
through 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
3535
has experience being implemented in a GraphQL library.
3636

3737
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*.
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*.
113113
RFCs are guided by a *champion* through a series of stages: *strawman*,
114114
*proposal*, *draft*, and *accepted* (or *rejected*), each of which has suggested
115115
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
117117
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
119119
occur on GitHub.
120120

121121
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*.
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
130130
partially-considered solutions. A *strawman* does not need to meet any entrance
131131
criteria. A *strawman's* goal is to prove or disprove a problem and guide
132132
discussion towards either rejection or a preferred solution. A *strawman* may
@@ -147,8 +147,8 @@ criteria for *proposal*.
147147
## Stage 1: *Proposal*
148148

149149
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
152152
both the problem and the solution via examples and spec edits. A *proposal*
153153
should 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

179179
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*
183183
must 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

225226
An *accepted* RFC is merged into the GraphQL spec's master branch by an editor
226227
and 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*.
234235
A *proposal* may become *rejected* for similar reasons as well as if it fails to
235236
reach consensus or loses the confidence of its *champion*. Likewise a *draft*
236237
may encounter unforeseen issues during implementations which cause it to lose

0 commit comments

Comments
 (0)
Please sign in to comment.