Expose v14 migration guide in sidebar and make some amendments (#7361)

website/src/docs/docs.json

@@ -431,6 +431,10 @@
             "path": "migrating",
             "title": "Migrating",
             "items": [
+              {
+                "path": "migrate-from-13-to-14",
+                "title": "Migrate from 13 to 14"
+              },
               {
                 "path": "migrate-from-12-to-13",
                 "title": "Migrate from 12 to 13"

website/src/docs/hotchocolate/v14/fetching-data/pagination.md

@@ -834,7 +834,7 @@ The following options can be configured.
 
 # Pagination defaults
 
-If we want to enforce consistent pagination defaults throughout our app, we can do so by setting the global `PagingOptions`.
+If we want to enforce consistent pagination defaults throughout our app, we can do so by modifying the global `PagingOptions`.
 
 ```csharp
 public class Startup
@@ -843,10 +843,7 @@ public class Startup
     {
         services
             .AddGraphQLServer()
-            .SetPagingOptions(new PagingOptions
-            {
-                MaxPageSize = 100
-            });
+            .ModifyPagingOptions(opt => opt.MaxPageSize = 100);
     }
 }
 ```

website/src/docs/hotchocolate/v14/migrating/migrate-from-13-to-14.md

@@ -1,5 +1,5 @@
 ---
-title: Migrate Hot Chocolate from 12 to 13
+title: Migrate Hot Chocolate from 13 to 14
 ---
 
 This guide will walk you through the manual migration steps to update your Hot Chocolate GraphQL server to version 14.
@@ -12,23 +12,67 @@ Start by installing the latest `14.x.x` version of **all** of the `HotChocolate.
 
 Things that have been removed or had a change in behavior that may cause your code not to compile or lead to unexpected behavior at runtime if not addressed.
 
+## New GID format
+
+This release introduces a more performant GID serializer, which also simplifies the underlying format of globally unique IDs.
+
+By default, the new serializer will be able to parse both the old and new ID format, while only emitting the new format.
+
+This change is breaking if your consumers depend on the format of the GIDs, by for example parsing them (which they shouldn't). If possible, strive to decouple your consumers from the internal ID format and exposing the underlying ID as a separate field on your type if necessary.
+
+If you don't want to switch to the new format yet, you can register the legacy serializer, which only supports parsing and emitting the old ID format:
+
+```csharp
+services
+  .AddGraphQLServer()
+  .AddLegacyNodeIdSerializer()
+  .AddGlobalObjectIdentification();
+```
+
+> Note: `AddLegacyNodeIdSerializer()` needs to be called before `AddGlobalObjectIdentification()`.
+
+### How to adopt incrementally in a distributed system
+
+None of your services can start to emit the new ID format, as long as there are services that can't parse the new format.
+
+Therefore, you'll first want to make sure that all of your services support parsing both the old and new format, while still emitting the old format.
+
+This can be done, by configuring the new default serializer to not yet emit the new format:
+
+```csharp
+services
+  .AddGraphQLServer()
+  .AddDefaultNodeIdSerializer(outputNewIdFormat: false)
+  .AddGlobalObjectIdentification();
+```
+
+> Note: `AddDefaultNodeIdSerializer()` needs to be called before `AddGlobalObjectIdentification()`.
+
+Once all of your services have been updated to this, you can start emitting the new format service-by-service, by removing the `AddDefaultNodeIdSerializer()` call and switching to the new default behavior:
+
+```csharp
+services
+  .AddGraphQLServer()
+  .AddGlobalObjectIdentification();
+```
+
 ## Builder APIs
 
 We have aligned all builder APIs to be more consistent and easier to use. Builders can now be created by using the static method `Builder.New()` and the `Build()` method to create the final object.
 
-## `IQueryRequestBuilder` replaced by `OperationRequestBuilder`
+### IQueryRequestBuilder replaced by OperationRequestBuilder
 
 The interface `IQueryRequestBuilder` and its implementations were replaced with `OperationRequestBuilder` which now supports building standard GraphQL operation requests as well as variable batch requests.
 
 The `Build()` method returns now a `IOperationRequest` which is implemented by `OperationRequest` and `VariableBatchRequest`.
 
 We have also simplified what the builder does and removed a lot of the convenience methods that allowed to add single variables to it. This has todo with the support of variable batching. Now, you have to provide the variable map directly.
 
-## `IQueryResultBuilder` replaced by `OperationResultBuilder`
+### IQueryResultBuilder replaced by OperationResultBuilder
 
 The interface `IQueryResultBuilder` and its implementations were replaced with `OperationResultBuilder` which produces an `OperationResult` on `Build()`.
 
-## `IQueryResult` replaced by `OperationResult`
+### IQueryResult replaced by OperationResult
 
 The interface `IQueryResultBuilder` and its implementations were replaced with `OperationResultBuilder` which produces an `OperationResult` on `Build()`.
 
@@ -41,3 +85,31 @@ Please ensure that your clients are sending date/time strings in the correct for
 # Deprecations
 
 Things that will continue to function this release, but we encourage you to move away from.
+
+## SetPagingOptions
+
+In an effort to align our configuration APIs, we're now also offering a delegate based configuration API for pagination options.
+
+**Before**
+
+```csharp
+services
+  .AddGraphQLServer()
+  .SetPagingOptions(new PagingOptions
+  {
+      MaxPageSize = 100,
+      DefaultPageSize = 25
+  });
+```
+
+**After**
+
+```csharp
+services
+  .AddGraphQLServer()
+  .ModifyPagingOptions(opt =>
+  {
+      opt.MaxPageSize = 100;
+      opt.DefaultPageSize = 25;
+  });
+```