Add guides for class-based mutations

Author: rmosolgo

guides/css/main.scss

@@ -98,8 +98,9 @@ pre {
   border: 1px solid $code-border;
   border-radius: $code-border-radius;
   background-color: $code-background;
-  margin: 10px 0px;
+  margin: 20px 0px;
   overflow-x: scroll;
+  line-height: 1.4rem;
 }
 
 p, li {
@@ -110,10 +111,6 @@ li {
   margin-left: 15px;
 }
 
-pre {
-  line-height: 1.4rem;
-}
-
 p, ul {
   margin-bottom: 10px;
 }
@@ -182,9 +179,11 @@ a:hover, a:hover code {
   ul {
     list-style: none;
     display: flex;
+    flex-wrap: wrap;
   }
 
   li {
+    padding-bottom: 10px;
     padding-right: 10px;
   }
 }

guides/guides.html

@@ -6,6 +6,7 @@
   - name: Types
   - name: Type Definitions
   - name: Fields
+  - name: Mutations
   - name: Relay
   - name: Subscriptions
   - name: GraphQL Pro

guides/mutations/mutation_classes.md

@@ -0,0 +1,82 @@
+---
+layout: guide
+search: true
+section: Mutations
+title: Mutation Classes
+desc: Use mutation classes to implement behavior, then hook them up to your schema.
+class_based_api: true
+index: 1
+---
+
+GraphQL _mutations_ are special fields: instead of reading data or performing calculations, they may _modify_ the application state. For example, mutation fields may:
+
+- Create, update or destroy records in the database
+- Establish associations between already-existing records in the database
+- Increment counters
+- Create, modify or delete files
+- Clear caches
+
+These actions are called _side effects_.
+
+Like all GraphQL fields, mutation fields:
+
+- Accept inputs, called _arguments_
+- Return values via _fields_
+
+GraphQL-Ruby includes two classes to help you write mutations:
+
+- {{ "GraphQL::Schema::Mutation" | api_doc }}, a bare-bones base class
+- {{ "GraphQL::Schema::RelayClassicMutation" | api_doc }}, a base class with a set of nice conventions that also supports the Relay Classic mutation specification.
+
+Besides those, you can also use the plain {% internal_link "field API", "/type_definitions/objects#fields" %} to write mutation fields.
+
+## Example mutation class
+
+You should add a base class to your application, for example:
+
+```ruby
+class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
+end
+```
+
+Then extend it for your mutations:
+
+```ruby
+class Mutations::CreateComment < Mutations::BaseMutation
+  argument :body, String, required: true
+  argument :post_id, ID, required: true
+
+  field :comment, Types::Comment, null: true
+  field :error_messages, [String], null: false
+
+  def resolve(body:, post_id:)
+    post = Post.find(post_id)
+    comment = post.comments.build(body: body, author: context[:current_user])
+    if comment.save
+      # Successful creation, return the created object with no errors
+      {
+        comment: comment,
+        errors: [],
+      }
+    else
+      # Failed save, return the errors to the client
+      {
+        comment: nil,
+        errors: comment.errors.full_messages
+      }
+    end
+  end
+end
+```
+
+The `#resolve` method should return a hash whose symbols match the `field` names.
+
+## Hooking up mutations
+
+Mutations must be attached to the mutation root using the `mutation:` keyword, for example:
+
+```ruby
+class Types::Mutation < Types::BaseObject
+  field :create_comment, mutation: Mutations::CreateComment
+end
+```

guides/mutations/mutation_root.md

@@ -0,0 +1,44 @@
+---
+layout: guide
+search: true
+section: Mutations
+title: Mutation Root
+desc: The Mutation object is the entry point for mutation operations.
+class_based_api: true
+index: 0
+---
+
+GraphQL mutations all begin with the `mutation` keyword:
+
+```graphql
+mutation($accountNumber: ID!, $newBalance: Int!) {
+# ^^^^ here
+  setAccountBalance(accountNumber: $accountNumber, newBalance: $newBalance) {
+    # ...
+  }
+}
+```
+
+Operations that begin with `mutation` get special treatment by the GraphQL runtime: root fields are guaranteed
+to be executed sequentially. This way, the effect of a series of mutations is predictable.
+
+Mutations are executed by a specific GraphQL object, `Mutation`. This object is defined like any other GraphQL object:
+
+```ruby
+class Types::Mutation < Types::BaseObject
+  # ...
+end
+```
+
+Then, it must be attached to your schema with the `mutation(...)` configuration:
+
+```ruby
+class Schema < GraphQL::Schema
+  # ...
+  mutation(Types::Mutation)
+end
+```
+
+Now, whenever an incoming request uses the `mutation` keyword, it will go to `Mutation`.
+
+See {% internal_link "Mutation Classes", "/mutations/mutation_classes" %} for some helpers to define mutation fields.