Add a style guide to the specification by benjie · Pull Request #1003 · graphql/graphql-spec

benjie · 2022-12-08T12:21:22Z

@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 · 2022-12-08T12:21:28Z

✅ 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 · 2023-01-06T08:36:11Z

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 · 2023-01-06T09:03:59Z

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

Add a style guide to the specification

f15350d

benjie mentioned this pull request Dec 8, 2022

Fixed capitalization of subsections in chapter 7. Response #981

Closed

benjie commented Dec 15, 2022

View reviewed changes

Comment thread STYLE_GUIDE.md Outdated

Update STYLE_GUIDE.md

585b6b6

mjmahone approved these changes Jan 5, 2023

View reviewed changes

Comment thread STYLE_GUIDE.md Outdated

benjie added 3 commits January 5, 2023 17:14

Hat tip to AP

806a97a

Clarify wording

f8c1c9b

Clarify details of hyphenated words

4e0fb9a

mjmahone approved these changes Jan 5, 2023

View reviewed changes

Comment thread STYLE_GUIDE.md

rivantsov reviewed Jan 5, 2023

View reviewed changes

Comment thread STYLE_GUIDE.md

Conform STYLE_GUIDE.md to the style guide

4183f1c

michaelstaib approved these changes Jan 6, 2023

View reviewed changes

benjie merged commit e736f78 into main Jan 6, 2023

benjie deleted the style-guide branch January 6, 2023 09:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a style guide to the specification#1003

Add a style guide to the specification#1003
benjie merged 6 commits intomainfrom
style-guide

benjie commented Dec 8, 2022

Uh oh!

netlify Bot commented Dec 8, 2022 •

edited

Loading

Uh oh!

Uh oh!

mjmahone left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benjie commented Jan 6, 2023

Uh oh!

michaelstaib left a comment

Uh oh!

benjie commented Jan 6, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

benjie commented Dec 8, 2022

Uh oh!

netlify Bot commented Dec 8, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for graphql-spec-draft ready!

Uh oh!

Uh oh!

mjmahone left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benjie commented Jan 6, 2023

Uh oh!

michaelstaib left a comment

Choose a reason for hiding this comment

Uh oh!

benjie commented Jan 6, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify Bot commented Dec 8, 2022 •

edited

Loading