Added first version of the beta6 upgrade guide.

Author: pmelab

doc/upgrade/beta6.md

@@ -0,0 +1,203 @@
+# Beta 6 Upgrade Guide
+## Schema changes
+These changes affect you if you are using the schema automatically generated by the `graphql_core` module.
+
+### Url Interfaces
+The type structure of the `Url` object changed. While before there have been just the `InternalUrl` and `ExternalUrl` types, the `InternalUrl` has become an interface that can resolve to different Url types, depending on the underlying route. The `DefaultInternalUrl` has the fields for context resolving and other generic rout information. The `EntityCanonicalUrl` has access to the underlying entity.
+
+In a nutshell, if you were using this kind of query:
+
+```
+query {
+	route(path: "/node/1") {
+    entity {
+		entityLabel
+    }
+  }
+}
+```
+
+It has to become this:
+```
+query {
+	route(path: "/node/1") {
+	  ... EntityCanonicalUrl {
+      entity {
+		  entityLabel
+      }
+    }
+  }
+}
+```
+
+### Entity Interfaces
+The interfaces for entities have been aligned with the entity interfaces in Drupal. There is an `EntityOwnable`, `EntityPublishable` and `EntityRevisionable` interface which now hold the respective fields.
+
+Before:
+```
+query {
+  entity:route(path: "/node/1") {
+    ... on EntityCanonicalUrl {
+      entity {
+        entityOwner {
+          uid
+        }
+        entityPublished
+        entityRevisions {
+          count
+        }
+      }
+    }
+  }
+}
+
+```
+
+After:
+
+```
+query {
+  entity:route(path: "/node/1") {
+    ... on EntityCanonicalUrl {
+      entity {
+        ... on EntityOwnable {
+          entityOwner {
+            uid
+          }
+        }
+        ... on EntityPublishable {
+          entityPublished
+        }
+        ... on EntityRevisionable {
+          entityRevisions {
+            count
+          }
+        }
+      }
+    }
+  }
+}
+
+```
+
+### Uppercased Enums
+Emumerations are uppercased now. For the schema generated by `graphql_core` this means language identifiers and image styles.
+
+Before:
+
+```
+query {
+  entity:route(path: "/node/1") {
+    ... on EntityCanonicalUrl {
+      entity {
+        entityTranslation(language: de) {
+	        ... on NodeArticle {
+            entityLabel
+            fieldImage {
+              derivative(style: thumbnail) {
+                url
+              }
+            }
+  	    	}
+        }
+  		}
+  	}
+	}
+}
+```
+
+After:
+```
+query {
+  entity:route(path: "/node/1") {
+    ... on EntityCanonicalUrl {
+      entity {
+        entityTranslation(language: DE) {
+	        ... on NodeArticle {
+            entityLabel
+            fieldImage {
+              derivative(style: THUMBNAIL) {
+                url
+              }
+            }
+  	    	}
+        }
+  		}
+  	}
+	}
+}
+```
+
+### Optimized simple fields
+Entity fields that contain only one property are simplified and directly emit that value.
+
+Before:
+```
+... on NodeArticle {
+  fieldPlainText {
+    value
+  }
+}
+```
+
+After:
+```
+... on NodeArticle {
+  fieldPlainText
+}
+```
+
+### Null in string results
+Due to the way the new execution library handles results, `null` values in Strings, an empty string field will not yield `null` but a string containing `”null”`.
+
+## API changes
+These changes affect you if you’ve been developing custom schema plugins.
+
+## API changes
+### Development flag
+The three settings for result cache, schema cache and field security have been replaced with one `development` flag, which turns the GraphQL module into development mode. This will also enable advanced error reporting in the underlying execution library.
+
+### Enum definitions
+`buildEnumValues` has to return an array of the following structure:
+
+```php
+[
+	'VALUE_A' => [
+	  'value' => 'a',
+    'description' => 'The letter a',
+  ],
+]
+```
+
+Instead of:
+```php
+[
+	[
+	  'value' => 'a',
+	  'name' => 'VALUE_A',
+    'description' => 'The letter a',
+  ],
+]
+```
+
+By convention the enums keys should be uppercases.
+
+### Resolve context
+The field plugins resolve methods receive an additional argument of type `ResolveContext`, that can be used to pass information to children down the query tree.
+
+If you field plugins have strict method annotations like this:
+```php
+public function resolveValues($value, $args, ResolveInfo $info) {
+...
+}
+```
+
+They have to be changed to:
+```php
+public function resolveValues($value, $args, ResolveContext $context, ResolveInfo $info) {
+...
+}
+```
+
+### Processors and persisted Queries
+The interfaces for the `QueryProcessor` and `QueryProvider` changed slightly. The `QueryProcessor` doesn’t accept a pair of `$query` and `$variables` any more, but an object of type `OperationParams`. The `QueryProviders` `$id` and `$version` arguments have been merged into one `$id` argument that has to contain both.