Add a style guide to the specification

[benjie]

@rivantsov pointed out in #981 that there is inconsistent capitalization in the spec.

I've done some research and have concluded that our style seems to most-closely match the AP style guide, so I have worked my way through every heading in the document and applied this style to them. I've also outlined the very basics of this in a style guide document.

You can see some of my analysis in this comment:

#981 (comment)

After that I expanded to looking at all headings in the document. I include below the before/after for the document headings, sorted alphabetically, using grep -hEr '(^#|^\*\*.*\*\*$)' . | sort -u

before

# A. Appendix: Notation Conventions
# B. Appendix: Grammar Summary
# Execution
# GraphQL
# Introspection
# Language
# Overview
# Response
# Type System
# Validation
# [Appendix: Grammar Summary](Appendix%20B%20--%20Grammar%20Summary.md)
# [Appendix: Notation Conventions](Appendix%20A%20--%20Notation%20Conventions.md)
# [Execution](Section%206%20--%20Execution.md)
# [Introspection](Section%204%20--%20Introspection.md)
# [Language](Section%202%20--%20Language.md)
# [Overview](Section%201%20--%20Overview.md)
# [Response](Section%207%20--%20Response.md)
# [Type System](Section%203%20--%20Type%20System.md)
# [Validation](Section%205%20--%20Validation.md)
## Algorithms
## Arguments
## Context-Free Grammar
## Descriptions
## Directives
## Document
## Document Syntax
## Documents
## Enums
## Executing Fields
## Executing Operations
## Executing Requests
## Executing Selection Sets
## Field Alias
## Fields
## Fragments
## Grammar Notation
## Grammar Semantics
## Ignored Tokens
## Input Objects
## Input Values
## Interfaces
## Lexical Tokens
## Lexical and Syntactical Grammar
## List
## Non-Null
## Objects
## Operations
## Response Format
## Scalars
## Schema
## Schema Introspection
## Selection Sets
## Serialization Format
## Source Text
## Type Name Introspection
## Type References
## Type System Extensions
## Types
## Unions
## Values
## Variables
### @deprecated
### @include
### @skip
### @specifiedBy
### All Variable Usages are Allowed
### All Variable Uses Defined
### All Variables Used
### Anonymous Operation Definitions
### Argument Names
### Argument Uniqueness
### Boolean
### Boolean Value
### Coercing Field Arguments
### Coercing Variable Values
### Combining List and Non-Null
### Comments
### Data
### Directives Are Defined
### Directives Are In Valid Locations
### Directives Are Unique Per Location
### Enum Extensions
### Enum Value
### Errors
### Executable Definitions
### Field Arguments
### Field Collection
### Field Deprecation
### Field Selection Merging
### Field Selections
### Float
### Float Value
### Fragment Declarations
### Fragment Spreads
### Handling Field Errors
### ID
### Ignored Tokens
### Inline Fragments
### Input Object Extensions
### Input Object Field Names
### Input Object Field Uniqueness
### Input Object Required Fields
### Input Object Values
### Input and Output Types
### Insignificant Commas
### Int
### Int Value
### Interface Extensions
### JSON Serialization
### Leaf Field Selections
### Lexical Tokens
### Line Terminators
### List Value
### Mutation
### Named Operation Definitions
### Names
### Normal and Serial Execution
### Null Value
### Object Extensions
### Punctuators
### Query
### Root Operation Types
### Scalar Extensions
### Schema Extension
### Serialized Map Ordering
### String
### String Value
### Subscription
### Subscription Operation Definitions
### The \_\_Directive Type
### The \_\_EnumValue Type
### The \_\_Field Type
### The \_\_InputValue Type
### The \_\_Schema Type
### The \_\_Type Type
### Type Conditions
### Type Extensions
### Union Extensions
### Validating Requests
### Value Completion
### Value Resolution
### Values of Correct Type
### Variable Uniqueness
### Variables Are Input Types
### White Space
### Wrapping Types
#### Fragment Name Uniqueness
#### Fragment Spread Type Existence
#### Fragment spread is possible
#### Fragment spread target defined
#### Fragment spreads must not form cycles
#### Fragments Must Be Used
#### Fragments On Composite Types
#### Lone Anonymous Operation
#### Operation Name Uniqueness
#### Required Arguments
#### Response Stream
#### Single root field
#### Source Stream
#### Unsubscribe
##### Abstract Spreads in Abstract Scope
##### Abstract Spreads in Object Scope
##### Object Spreads In Abstract Scope
##### Object Spreads In Object Scope
**Allowing optional variables when default values exist**
**Arguments are unordered**
**Block Strings**
**Built-in Directives**
**Built-in Scalars**
**Byte order mark**
**Circular References**
**Coercing Results**
**Conformance**
**Conforming Algorithms**
**Constraints**
**Copyright notice**
**Custom Directives**
**Custom Scalars**
**Default Root Operation Type Names**
**Delivery Agnostic**
**Deprecation**
**Directive order is significant**
**Enum**
**Error result format**
**Errors and Non-Null Fields**
**Escape Sequences**
**Event Streams**
**Examples**
**Explanatory Text**
**Field Ordering**
**Field errors**
**First Class Documentation**
**Formal Specification**
**Input Coercion**
**Input Object**
**Input object fields are unordered**
**Interface Spreads in implemented Interface Scope**
**Interface**
**Interfaces Implementing Interfaces**
**Introduction**
**Lexical Analysis & Syntactic Parse**
**Licensing**
**List**
**Lookahead Restrictions**
**Merging Selection Sets**
**Non-Normative Portions**
**Non-Null**
**Nullable vs. Optional**
**Object**
**Optionality and Lists**
**Parameterized Grammar Productions**
**Query shorthand**
**Request errors**
**Reserved Names**
**Resolving Abstract Types**
**Result Coercion and Serialization**
**Result Coercion**
**Scalar**
**Schema Introspection Schema**
**Schema Validation**
**Semantics**
**Static Semantics**
**Supporting Subscriptions at Scale**
**Type Validation**
**Type system evolution**
**Union**
**Validation**
**Variable use within Fragments**

after

# A. Appendix: Notation Conventions
# B. Appendix: Grammar Summary
# Execution
# GraphQL
# Introspection
# Language
# Overview
# Response
# Type System
# Validation
# [Appendix: Grammar Summary](Appendix%20B%20--%20Grammar%20Summary.md)
# [Appendix: Notation Conventions](Appendix%20A%20--%20Notation%20Conventions.md)
# [Execution](Section%206%20--%20Execution.md)
# [Introspection](Section%204%20--%20Introspection.md)
# [Language](Section%202%20--%20Language.md)
# [Overview](Section%201%20--%20Overview.md)
# [Response](Section%207%20--%20Response.md)
# [Type System](Section%203%20--%20Type%20System.md)
# [Validation](Section%205%20--%20Validation.md)
## Algorithms
## Arguments
## Context-Free Grammar
## Descriptions
## Directives
## Document
## Document Syntax
## Documents
## Enums
## Executing Fields
## Executing Operations
## Executing Requests
## Executing Selection Sets
## Field Alias
## Fields
## Fragments
## Grammar Notation
## Grammar Semantics
## Ignored Tokens
## Input Objects
## Input Values
## Interfaces
## Lexical Tokens
## Lexical and Syntactical Grammar
## List
## Non-Null
## Objects
## Operations
## Response Format
## Scalars
## Schema
## Schema Introspection
## Selection Sets
## Serialization Format
## Source Text
## Type Name Introspection
## Type References
## Type System Extensions
## Types
## Unions
## Values
## Variables
### @deprecated
### @include
### @skip
### @specifiedBy
### All Variable Usages Are Allowed
### All Variable Uses Defined
### All Variables Used
### Anonymous Operation Definitions
### Argument Names
### Argument Uniqueness
### Boolean
### Boolean Value
### Coercing Field Arguments
### Coercing Variable Values
### Combining List and Non-Null
### Comments
### Data
### Directives Are Defined
### Directives Are Unique per Location
### Directives Are in Valid Locations
### Enum Extensions
### Enum Value
### Errors
### Executable Definitions
### Field Arguments
### Field Collection
### Field Deprecation
### Field Selection Merging
### Field Selections
### Float
### Float Value
### Fragment Declarations
### Fragment Spreads
### Handling Field Errors
### ID
### Ignored Tokens
### Inline Fragments
### Input Object Extensions
### Input Object Field Names
### Input Object Field Uniqueness
### Input Object Required Fields
### Input Object Values
### Input and Output Types
### Insignificant Commas
### Int
### Int Value
### Interface Extensions
### JSON Serialization
### Leaf Field Selections
### Lexical Tokens
### Line Terminators
### List Value
### Mutation
### Named Operation Definitions
### Names
### Normal and Serial Execution
### Null Value
### Object Extensions
### Punctuators
### Query
### Root Operation Types
### Scalar Extensions
### Schema Extension
### Serialized Map Ordering
### String
### String Value
### Subscription
### Subscription Operation Definitions
### The \_\_Directive Type
### The \_\_EnumValue Type
### The \_\_Field Type
### The \_\_InputValue Type
### The \_\_Schema Type
### The \_\_Type Type
### Type Conditions
### Type Extensions
### Union Extensions
### Validating Requests
### Value Completion
### Value Resolution
### Values of Correct Type
### Variable Uniqueness
### Variables Are Input Types
### White Space
### Wrapping Types
#### Fragment Name Uniqueness
#### Fragment Spread Is Possible
#### Fragment Spread Target Defined
#### Fragment Spread Type Existence
#### Fragment Spreads Must Not Form Cycles
#### Fragments Must Be Used
#### Fragments on Composite Types
#### Lone Anonymous Operation
#### Operation Name Uniqueness
#### Required Arguments
#### Response Stream
#### Single Root Field
#### Source Stream
#### Unsubscribe
##### Abstract Spreads in Abstract Scope
##### Abstract Spreads in Object Scope
##### Object Spreads in Abstract Scope
##### Object Spreads in Object Scope
**Allowing Optional Variables When Default Values Exist**
**Arguments Are Unordered**
**Block Strings**
**Built-in Directives**
**Built-in Scalars**
**Byte Order Mark**
**Circular References**
**Coercing Results**
**Conformance**
**Conforming Algorithms**
**Constraints**
**Copyright Notice**
**Custom Directives**
**Custom Scalars**
**Default Root Operation Type Names**
**Delivery Agnostic**
**Deprecation**
**Directive Order Is Significant**
**Enum**
**Error Result Format**
**Errors and Non-Null Fields**
**Escape Sequences**
**Event Streams**
**Examples**
**Explanatory Text**
**Field Errors**
**Field Ordering**
**First Class Documentation**
**Formal Specification**
**Input Coercion**
**Input Object Fields Are Unordered**
**Input Object**
**Interface Spreads in Implemented Interface Scope**
**Interface**
**Interfaces Implementing Interfaces**
**Introduction**
**Lexical Analysis & Syntactic Parse**
**Licensing**
**List**
**Lookahead Restrictions**
**Merging Selection Sets**
**Non-Normative Portions**
**Non-Null**
**Nullable vs. Optional**
**Object**
**Optionality and Lists**
**Parameterized Grammar Productions**
**Query Shorthand**
**Request Errors**
**Reserved Names**
**Resolving Abstract Types**
**Result Coercion and Serialization**
**Result Coercion**
**Scalar**
**Schema Introspection Schema**
**Schema Validation**
**Semantics**
**Static Semantics**
**Supporting Subscriptions at Scale**
**Type System Evolution**
**Type Validation**
**Union**
**Validation**
**Variable Use Within Fragments**

Closes #981

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	4183f1c
🔍 Latest deploy log	https://app.netlify.com/sites/graphql-spec-draft/deploys/63b7dee9177c82000849b1bd
😎 Deploy Preview	https://deploy-preview-1003--graphql-spec-draft.netlify.app/
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[mjmahone]

One nit but the actual changes look good.

[benjie]

I looked into using vale.sh but that looks like it's going to be a fair amount of setup (not least because it's a native binary, so getting it running everywhere is a bit more complex than an npm module) and I'm unfamiliar with the tool, so I suggest we merge this as is as a good start, and then continue with vale.sh as a separate work.

[michaelstaib]

Looks good!

[benjie]

Two TSC approvals, editorial only, based on last night's discussion I'm going to go ahead and merge it 👍