Add a style guide to the specification (#1003)

Author: benjie

STYLE_GUIDE.md

@@ -0,0 +1,57 @@
+**This document is a work in progress.**
+
+# GraphQL Specification Style Guide
+
+This document outlines the styles used in the GraphQL spec to aid editorial and
+consistency. The writing style portions are inspired by the AP style guide. When
+making changes to the GraphQL specification, please aim to be consistent with
+this style guide.
+
+## Auto-Formatting
+
+The GraphQL specification is formatted using the `prettier` tool, so you should
+not need to think about gaps between paragraphs and titles, nor about word
+wrapping - this is handled for you.
+
+## Headings
+
+The GraphQL specification uses two types of headings: numbered headings and
+unnumbered headings. All headings should be written in Title Case (see below).
+
+### Numbered Headings
+
+Lines beginning with a `#` will become numbered headings in the spec-md output.
+
+```
+# H1
+## H2
+### H3
+#### H4
+##### H5
+```
+
+### Unnumbered Headings
+
+Unnumbered headings are added to split large blocks of text up without impacting
+the spec numbering system. In the output are styled similarly to an H4. An
+unnumbered heading is a line on its own that is bolded:
+
+```md
+\*\*This Is an Example of an Unnumbered Heading\*\*
+```
+
+### Title Case
+
+Title case is used for headings. Every word in a heading (including words after
+hyphens) should be capitalized, with the following exceptions:
+
+- articles: a, an, the
+- conjunctions under 4 letters in length: for, and, nor, but, or, yet, so, as,
+  if
+- prepositions under 4 letters in length: in, at, to, on, off, of, for, vs., per
+- directive names and type names are unchanged: @include, @specifiedBy,
+  \_\_EnumValue, \_\_Schema
+
+All elements in hyphenated words follow the same rules, e.g. headings may
+contain `Non-Null`, `Context-Free`, `Built-in` (`in` is a preposition, so is not
+capitalized).

spec/GraphQL.md

@@ -26,7 +26,7 @@ specification can be found at permalinks that match their
 working draft release can be found at
 [https://spec.graphql.org/draft](https://spec.graphql.org/draft).
 
-**Copyright notice**
+**Copyright Notice**
 
 Copyright © 2015-2018, Facebook, Inc.
 

spec/Section 2 -- Language.md

@@ -164,7 +164,7 @@ significant way, for example a {StringValue} may contain white space characters.
 No {Ignored} may appear _within_ a {Token}, for example no white space
 characters are permitted between the characters defining a {FloatValue}.
 
-**Byte order mark**
+**Byte Order Mark**
 
 UnicodeBOM :: "Byte Order Mark (U+FEFF)"
 
@@ -306,7 +306,7 @@ mutation {
 }
 ```
 
-**Query shorthand**
+**Query Shorthand**
 
 If a document contains only one operation and that operation is a query which
 defines no variables and has no directives applied to it then that operation may
@@ -439,7 +439,7 @@ Many arguments can exist for a given field:
 }
 ```
 
-**Arguments are unordered**
+**Arguments Are Unordered**
 
 Arguments may be provided in any syntactic order and maintain identical semantic
 meaning.
@@ -1130,7 +1130,7 @@ curly-braces `{ }`. The values of an object literal may be any input value
 literal or variable (ex. `{ name: "Hello world", score: 1.0 }`). We refer to
 literal representation of input objects as "object literals."
 
-**Input object fields are unordered**
+**Input Object Fields Are Unordered**
 
 Input object fields may be provided in any syntactic order and maintain
 identical semantic meaning.
@@ -1207,7 +1207,7 @@ size `60`:
 }
 ```
 
-**Variable use within Fragments**
+**Variable Use Within Fragments**
 
 Variables can be used within fragments. Variables have global scope with a given
 operation, so a variable used within a fragment must be declared in any
@@ -1282,7 +1282,7 @@ As future versions of GraphQL adopt new configurable execution capabilities,
 they may be exposed via directives. GraphQL services and tools may also provide
 any additional _custom directive_ beyond those described here.
 
-**Directive order is significant**
+**Directive Order Is Significant**
 
 Directives may be provided in a specific syntactic order which may have semantic
 interpretation.

spec/Section 5 -- Validation.md

@@ -19,7 +19,7 @@ or development-time tool should report validation errors and not allow the
 formulation or execution of requests known to be invalid at that given point in
 time.
 
-**Type system evolution**
+**Type System Evolution**
 
 As GraphQL type system schema evolves over time by adding new types and new
 fields, it is possible that a request which was previously valid could later
@@ -251,7 +251,7 @@ query getName {
 
 ### Subscription Operation Definitions
 
-#### Single root field
+#### Single Root Field
 
 **Formal Specification**
 
@@ -910,7 +910,7 @@ fragment inlineNotExistingType on Dog {
 }
 ```
 
-#### Fragments On Composite Types
+#### Fragments on Composite Types
 
 **Formal Specification**
 
@@ -987,7 +987,7 @@ Field selection is also determined by spreading fragments into one another. The
 selection set of the target fragment is combined into the selection set at the
 level at which the target fragment is referenced.
 
-#### Fragment spread target defined
+#### Fragment Spread Target Defined
 
 **Formal Specification**
 
@@ -1008,7 +1008,7 @@ is a validation error if the target of a spread is not defined.
 }
 ```
 
-#### Fragment spreads must not form cycles
+#### Fragment Spreads Must Not Form Cycles
 
 **Formal Specification**
 
@@ -1093,7 +1093,7 @@ fragment ownerFragment on Human {
 }
 ```
 
-#### Fragment spread is possible
+#### Fragment Spread Is Possible
 
 **Formal Specification**
 
@@ -1118,7 +1118,7 @@ type matches the type condition. They also are spread within the context of a
 parent type. A fragment spread is only valid if its type condition could ever
 apply within the parent type.
 
-##### Object Spreads In Object Scope
+##### Object Spreads in Object Scope
 
 In the scope of an object type, the only valid object type fragment spread is
 one that applies to the same type that is in scope.
@@ -1181,7 +1181,7 @@ that if one inspected the contents of the {CatOrDogNameFragment} you could note
 that no valid results would ever be returned. However we do not specify this as
 invalid because we only consider the fragment declaration, not its body.
 
-##### Object Spreads In Abstract Scope
+##### Object Spreads in Abstract Scope
 
 Union or interface spreads can be used within the context of an object type
 fragment, but only if the object type is one of the possible types of that
@@ -1266,7 +1266,7 @@ fragment sentientFragment on Sentient {
 is not valid because there exists no type that implements both {Pet} and
 {Sentient}.
 
-**Interface Spreads in implemented Interface Scope**
+**Interface Spreads in Implemented Interface Scope**
 
 Additionally, an interface type fragment can always be spread into an interface
 scope which it implements.
@@ -1447,7 +1447,7 @@ input object field is optional.
 GraphQL services define what directives they support. For each usage of a
 directive, the directive must be available on that service.
 
-### Directives Are In Valid Locations
+### Directives Are in Valid Locations
 
 **Formal Specification**
 
@@ -1473,7 +1473,7 @@ query @skip(if: $foo) {
 }
 ```
 
-### Directives Are Unique Per Location
+### Directives Are Unique per Location
 
 **Formal Specification**
 
@@ -1853,7 +1853,7 @@ fragment isHouseTrainedFragment on Dog {
 This document is not valid because {queryWithExtraVar} defines an extraneous
 variable.
 
-### All Variable Usages are Allowed
+### All Variable Usages Are Allowed
 
 **Formal Specification**
 
@@ -1971,7 +1971,7 @@ query listToNonNullList($booleanList: [Boolean]) {
 This would fail validation because a `[T]` cannot be passed to a `[T]!`.
 Similarly a `[T]` cannot be passed to a `[T!]`.
 
-**Allowing optional variables when default values exist**
+**Allowing Optional Variables When Default Values Exist**
 
 A notable exception to typical variable type compatibility is allowing a
 variable definition with a nullable type to be provided to a non-null location

spec/Section 7 -- Response.md

@@ -66,7 +66,7 @@ If the `data` entry in the response is present (including if it is the value
 {null}), the `errors` entry must be present if and only if one or more _field
 error_ was raised during execution.
 
-**Request errors**
+**Request Errors**
 
 :: A _request error_ is an error raised during a _request_ which results in no
 response data. Typically raised before execution begins, a request error may
@@ -79,7 +79,7 @@ If a request error is raised, the `data` entry in the response must not be
 present, the `errors` entry must include the error, and request execution should
 be halted.
 
-**Field errors**
+**Field Errors**
 
 :: A _field error_ is an error raised during the execution of a particular field
 which results in partial response data. This may occur due to an internal error
@@ -92,7 +92,7 @@ is produced (see [Handling Field Errors](#sec-Handling-Field-Errors)). The
 `data` entry in the response must be present. The `errors` entry should include
 this error.
 
-**Error result format**
+**Error Result Format**
 
 Every error must contain an entry with the key `message` with a string
 description of the error intended for the developer as a guide to understand and