CONTRIBUTING.md
1
# GraphQL Specification Contribution Guide
3
GraphQL is still an evolving language. This repository contains the
4
specification text as well as Pull Requests with suggested improvements and
5
contributions.
7
Contributions that do not change the interpretation of the spec but instead
8
improve legibility, fix editorial errors, clear up ambiguity and improve
9
examples are encouraged. These "editorial changes" will normally be given the
10
["✏ Editorial" label](https://github.com/graphql/graphql-spec/issues?q=sort%3Aupdated-desc+is%3Aopen+label%3A%22%E2%9C%8F%EF%B8%8F+Editorial%22)
11
and are often merged by a spec editor with little process.
13
However, contributions that _do_ meaningfully change the interpretation of the
14
spec must follow an RFC (Request For Comments) process led by a _champion_
15
through a series of _stages_ intended to improve _visibility_, allow for
16
_discussion_ to reach the best solution, and arrive at _consensus_. This process
17
becomes ever more important as GraphQL's community broadens.
19
When proposing or weighing-in on any issue or pull request, consider the
20
[Code of Conduct](https://github.com/graphql/foundation/blob/main/CODE-OF-CONDUCT.md)
21
to better understand expected and unacceptable behavior.
23
## Contributing to GraphQL Libraries
25
A common point of confusion for those who wish to contribute to GraphQL is where
26
to start. In fact, you may have found yourself here after attempting to make an
27
improvement to a GraphQL library. Should a new addition be made to the GraphQL
28
spec first or a GraphQL library first? Admittedly, this can become a bit of a
29
[chicken-or-egg](https://en.wikipedia.org/wiki/Chicken_or_the_egg) dilemma.
31
GraphQL libraries seek to be "spec compliant", which means they discourage
32
changes that cause them to behave differently from the spec as written. However,
33
they also encourage pull requests for changes that accompany an RFC _proposal_
34
or RFC _draft_. In fact, a spec contribution RFC won't be _accepted_ until it
35
has experience being implemented in a GraphQL library.
37
To allow a library to remain spec compliant while also implementing _proposals_
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_.
42
## Guiding Principles
44
GraphQL's evolution is guided by a few principles. Suggested contributions
45
should use these principles to guide the details of an RFC and decisions to move
46
forward. See editor Lee Byron talk about
47
[guiding principles at GraphQL Europe 2017](https://youtu.be/mePT9MNTM98?t=17m9s).
49
- **Backwards compatibility**
51
Once a query is written, it should always mean the same thing and return the
52
same shaped result. Future changes should not change the meaning of existing
53
schema or requests or in any other way cause an existing compliant GraphQL
54
service to become non-compliant for prior versions of the spec.
56
- **Performance is a feature**
58
GraphQL typically avoids syntax or behaviors that could jeopardize runtime
59
efficiency, or that make demands of GraphQL services which cannot efficiently
60
be fulfilled.
62
- **Favor no change**
64
As GraphQL is implemented in over a dozen languages under the collaboration of
65
hundreds of individuals, incorporating any change has a high cost.
66
Accordingly, proposed changes must meet a very high bar of added value. The
67
burden of proof is on the contributor to illustrate this value.
69
- **Enable new capabilities motivated by real use cases**
71
Every change should intend on unlocking a real and reasonable use case. Real
72
examples are always more compelling than theoretical ones, and common
73
scenarios are more compelling than rare ones. RFCs should do more than offer a
74
different way to reach an already achievable outcome.
76
- **Simplicity and consistency over expressiveness and terseness**
78
Plenty of behaviors and patterns found in other languages are intentionally
79
absent from GraphQL. "Possible but awkward" is often favored over more complex
80
alternatives. Simplicity (e.g. fewer concepts) is more important than
81
expressing more sophisticated ideas or writing less.
83
- **Preserve option value**
85
It's hard to know what the future brings; whenever possible, decisions should
86
be made that allow for more options in the future. Sometimes this is
87
unintuitive: spec rules often begin more strict than necessary with a future
88
option to loosen when motivated by a real use case.
90
- **Understandability is just as important as correctness**
92
The GraphQL spec, despite describing technical behavior, is intended to be
93
read by people. Use natural tone and include motivation and examples.
94
95
## RFC Contribution Champions
96
97
Contributing to GraphQL requires a lot of dedicated work. To set clear
98
expectations and provide accountability, each proposed RFC (request for
99
comments) must have a _champion_ who is responsible for addressing feedback and
100
completing next steps. An RFC may have multiple _champions_. The spec editors
101
are not responsible for completing RFCs which lack a _champion_ (though an
102
editor may be a _champion_ for an RFC).
104
An RFC which does not have a _champion_ may not progress through stages, and can
105
become stale. Stale proposals may be picked up by a new _champion_ or may be
106
_rejected_.
107
108
## RFC Contribution Stages
109
110
RFCs are guided by a _champion_ through a series of stages: _strawman_,
111
_proposal_, _draft_, and _accepted_ (or _rejected_), each of which has suggested
112
entrance criteria and next steps detailed below. RFCs typically advance one
113
stage at a time, but may advance multiple stages at a time. Stage advancements
114
typically occur during [Working Group](https://github.com/graphql/graphql-wg)
115
meetings, but may also occur on GitHub.
117
In general, it's preferable to start with a pull request so that we can best
118
evaluate the RFC in detail. However, starting with an issue is also permitted if
119
the full details are not worked out.
120
121
All RFCs start as either a _strawman_ or _proposal_.
123
## Stage 0: _Strawman_
125
An RFC at the _strawman_ stage captures a described problem or
126
partially-considered solutions. A _strawman_ does not need to meet any entrance
127
criteria. A _strawman's_ goal is to prove or disprove a problem and guide
128
discussion towards either rejection or a preferred solution. A _strawman_ may be
129
an issue or a pull request (though an illustrative pull request is preferrable).
131
_There is no entrance criteria for a Strawman_
133
As implied by the name
134
[strawman](https://en.wikipedia.org/wiki/Straw_man_proposal), the goal at this
135
stage is to knock it down (_reject_) by considering other possible related
136
solutions, showing that the motivating problem can be solved with no change to
137
the specification, or that it is not aligned with the _guiding principles_.
139
Once determined that the _strawman_ is compelling, it should seek the entrance
140
criteria for _proposal_.
142
## Stage 1: _Proposal_
144
An RFC at the _proposal_ stage is a solution to a problem with enough fidelity
145
to be discussed in detail. It must be backed by a willing _champion_. A
146
_proposal_'s goal is to make a compelling case for acceptance by describing both
147
the problem and the solution via examples and spec edits. A _proposal_ should be
148
a pull request.
150
_Entrance criteria:_
152
- Identified _champion_
153
- Clear explanation of problem and solution
154
- Illustrative examples
155
- Incomplete spec edits
156
- Identification of potential concerns, challenges, and drawbacks
158
A _proposal_ is subject to the same discussion as a _strawman_: ensuring that it
159
is well aligned with the _guiding principles_, is a problem worth solving, and
160
is the preferred solution to that problem. A _champion_ is not expected to have
161
confidence in every detail at this stage and should instead focus on identifying
162
and resolving issues and edge-cases. To better understand the technical
163
ramifications of the _proposal_, a _champion_ is encouraged to implement it in a
164
GraphQL library.
166
Most _proposals_ are expected to evolve or change and may be rejected.
167
Therefore, it is unwise to rely on a _proposal_ in a production GraphQL service.
168
GraphQL libraries _may_ implement _proposals_, though are encouraged to not
169
enable the _proposed_ feature without explicit opt-in.
171
## Stage 2: _Draft_
173
An RFC at the _draft_ stage is a fully formed solution. There is working group
174
consensus the problem identified should be solved, and this particular solution
175
is preferred. A _draft's_ goal is to precisely and completely describe the
176
solution and resolve any concerns through library implementations. A _draft_
177
must be a pull request.
178
179
_Entrance criteria:_
181
- Consensus the solution is preferred (typically via Working Group)
182
- Resolution of identified concerns and challenges
183
- Precisely described with spec edits
184
- Compliant implementation in GraphQL.js (might not be merged)
186
A _proposal_ becomes a _draft_ when the set of problems or drawbacks have been
187
fully considered and accepted or resolved, and the solution is deemed desirable.
188
A _draft_'s goal is to complete final spec edits that are ready to be merged and
189
implement the _draft_ in GraphQL libraries along with tests to gain confidence
190
that the spec text is sufficient.
192
_Drafts_ may continue to evolve and change, occasionally dramatically, and are
193
not guaranteed to be accepted. Therefore, it is unwise to rely on a _draft_ in a
194
production GraphQL Service. GraphQL libraries _should_ implement _drafts_ to
195
provide valuable feedback, though are encouraged not to enable the _draft_
196
feature without explicit opt-in when possible.
197
198
## Stage 3: _Accepted_
200
An RFC at the _accepted_ stage is a completed solution. According to a spec
201
editor it is ready to be merged as-is into the spec document. The RFC is ready
202
to be deployed in GraphQL libraries. An _accepted_ RFC must be implemented in
203
GraphQL.js.
205
_Entrance criteria:_
207
- Consensus the solution is complete (via editor or working group)
208
- Complete spec edits, including examples and prose
209
- Compliant implementation in GraphQL.js (fully tested and merged or ready to
210
merge)
212
A _draft_ is _accepted_ when the working group or editor has been convinced via
213
implementations and tests that it appropriately handles all edge cases; that the
214
spec changes not only precisely describe the new syntax and semantics but
215
include sufficient motivating prose and examples; and that the RFC includes
216
edits to any other affected areas of the spec. Once _accepted_, its _champion_
217
should encourage adoption of the RFC by opening issues or pull requests on other
218
popular GraphQL libraries.
220
An _accepted_ RFC is merged into the GraphQL spec's main branch by an editor and
221
will be included in the next released revision.
223
## Stage X: _Rejected_
225
An RFC may be _rejected_ at any point and for any reason. Most rejections occur
226
when a _strawman_ is proven to be unnecessary, is misaligned with the _guiding
227
principles_, or fails to meet the entrance criteria to become a _proposal_. A
228
_proposal_ may become _rejected_ for similar reasons as well as if it fails to
229
reach consensus or loses the confidence of its _champion_. Likewise a _draft_
230
may encounter unforeseen issues during implementations which cause it to lose
231
consensus or the confidence of its _champion_.
233
RFCs which have lost a _champion_ will not be _rejected_ immediately, but may
234
become _rejected_ if they fail to attract a new _champion_.
236
Once _rejected_, an RFC will typically not be reconsidered. Reconsideration is
237
possible if a _champion_ believes the original reason for rejection no longer
238
applies due to new circumstances or new evidence.