Merge branch 'main' into benjie/incremental-common

Author: benjie

CONTRIBUTING.md

@@ -6,8 +6,9 @@ contributions.
 
 Contributions that 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.
+examples are encouraged. These "editorial changes" will normally be given the
+["✏ 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)
+and are often merged by a spec editor with little process.
 
 However, contributions that _do_ meaningfully change the interpretation of the
 spec must follow an RFC (Request For Comments) process led by a _champion_

STYLE_GUIDE.md

@@ -82,3 +82,25 @@ MyAlgorithm(argOne, argTwo):
     - Let {something} be {true}.
 - Return {something}.
 ```
+
+## Definitions
+
+For important terms, use
+[Spec Markdown definition paragraphs](https://spec-md.com/#sec-Definition-Paragraph).
+
+Definition paragraphs start with `::` and add the matching italicized term to
+the [specification index](https://spec.graphql.org/draft/#index), making it easy
+to reference them.
+
+## Tone of voice
+
+The GraphQL specification is a reference document and should use neutral and
+descriptive tone of voice.
+
+**Favor the present tense**
+
+The present tense is usually clearer and shorter:
+
+✅ Present: The client then sends a request to the server.
+
+❌ Future: The client will then send a request to the server.

spec/Section 5 -- Validation.md

@@ -420,7 +420,7 @@ FieldsInSetCanMerge(set):
 
 - Let {fieldsForName} be the set of selections with a given response name in
   {set} including visiting fragments and inline fragments.
-- Given each pair of members {fieldA} and {fieldB} in {fieldsForName}:
+- Given each pair of distinct members {fieldA} and {fieldB} in {fieldsForName}:
   - {SameResponseShape(fieldA, fieldB)} must be true.
   - If the parent types of {fieldA} and {fieldB} are equal or if either is not
     an Object Type:
@@ -452,7 +452,8 @@ SameResponseShape(fieldA, fieldB):
   selection set of {fieldB}.
 - Let {fieldsForName} be the set of selections with a given response name in
   {mergedSet} including visiting fragments and inline fragments.
-- Given each pair of members {subfieldA} and {subfieldB} in {fieldsForName}:
+- Given each pair of distinct members {subfieldA} and {subfieldB} in
+  {fieldsForName}:
   - If {SameResponseShape(subfieldA, subfieldB)} is {false}, return {false}.
 - Return {true}.
 

spec/Section 6 -- Execution.md

@@ -158,11 +158,11 @@ ExecuteMutation(mutation, schema, variableValues, initialValue):
 ### Subscription
 
 If the operation is a subscription, the result is an _event stream_ called the
-"Response Stream" where each event in the event stream is the result of
-executing the operation for each new event on an underlying "Source Stream".
+_response stream_ where each event in the event stream is the result of
+executing the operation for each new event on an underlying _source stream_.
 
 Executing a subscription operation creates a persistent function on the service
-that maps an underlying Source Stream to a returned Response Stream.
+that maps an underlying _source stream_ to a returned _response stream_.
 
 Subscribe(subscription, schema, variableValues, initialValue):
 
@@ -250,9 +250,9 @@ service details should be chosen by the implementing service.
 
 #### Source Stream
 
-A Source Stream is an _event stream_ representing a sequence of root values,
-each of which will trigger a GraphQL execution. Like field value resolution, the
-logic to create a Source Stream is application-specific.
+:: A _source stream_ is an _event stream_ representing a sequence of root
+values, each of which will trigger a GraphQL execution. Like field value
+resolution, the logic to create a _source stream_ is application-specific.
 
 CreateSourceEventStream(subscription, schema, variableValues, initialValue):
 
@@ -287,7 +287,7 @@ operation type.
 
 #### Response Stream
 
-Each event from the underlying Source Stream triggers execution of the
+Each event from the underlying _source stream_ triggers execution of the
 subscription _selection set_ using that event's value as the {initialValue}.
 
 MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues):
@@ -328,7 +328,7 @@ Note: The {ExecuteSubscriptionEvent()} algorithm is intentionally similar to
 
 #### Unsubscribe
 
-Unsubscribe cancels the Response Stream when a client no longer wishes to
+Unsubscribe cancels the _response stream_ when a client no longer wishes to
 receive payloads for a subscription. This in turn also cancels the Source
 Stream, which is a good opportunity to clean up any other resources used by the
 subscription.

spec/Section 7 -- Response.md

@@ -10,7 +10,12 @@ the case that any _field error_ was raised on a field and was replaced with
 
 ## Response Format
 
-A response to a GraphQL request must be a map.
+A GraphQL request returns either a _response_ or a _response stream_.
+
+### Response
+
+:: A GraphQL request returns a _response_ when the GraphQL operation is a query
+or mutation. A _response_ must be a map.
 
 If the request raised any errors, the response map must contain an entry with
 key `errors`. The value of this entry is described in the "Errors" section. If
@@ -35,6 +40,11 @@ Note: When `errors` is present in the response, it may be helpful for it to
 appear first when serialized to make it more clear when errors are present in a
 response during debugging.
 
+### Response Stream
+
+:: A GraphQL request returns a _response stream_ when the GraphQL operation is a
+subscription. A _response stream_ must be a stream of _response_.
+
 ### Data
 
 The `data` entry in the response will be the result of the execution of the
@@ -107,14 +117,8 @@ syntax element.
 If an error can be associated to a particular field in the GraphQL result, it
 must contain an entry with the key `path` that details the path of the response
 field which experienced the error. This allows clients to identify whether a
-`null` result is intentional or caused by a runtime error.
-
-If present, this field must be a list of path segments starting at the root of
-the response and ending with the field associated with the error. Path segments
-that represent fields must be strings, and path segments that represent list
-indices must be 0-indexed integers. If the error happens in an aliased field,
-the path to the error must use the aliased name, since it represents a path in
-the response, not in the request.
+`null` result is intentional or caused by a runtime error. The value of this
+_path entry_ is described in the [Path](#sec-Path) section.
 
 For example, if fetching one of the friends' names fails in the following
 operation:
@@ -244,6 +248,21 @@ discouraged.
 }
 ```
 
+### Path
+
+:: A _path entry_ is an entry within an _error result_ that allows for
+association with a particular field reached during GraphQL execution.
+
+The value for a _path entry_ must be a list of path segments starting at the
+root of the response and ending with the field to be associated with. Path
+segments that represent fields must be strings, and path segments that represent
+list indices must be 0-indexed integers. If a path segment is associated with an
+aliased field it must use the aliased name, since it represents a path in the
+response, not in the request.
+
+When the _path entry_ is present on an _error result_, it identifies the
+response field which experienced the error.
+
 ## Serialization Format
 
 GraphQL does not require a specific serialization format. However, clients