From 9e9401277f5d7688dec0970355653a2262bf072c Mon Sep 17 00:00:00 2001
From: Laurin Quast <laurinquast@googlemail.com>
Date: Thu, 8 Feb 2024 13:33:24 +0100
Subject: [PATCH] docs: add stitching project change product update (#3944)

---
 .../docs/src/components/product-updates.tsx   |  4 +--
 ...-08-upcoming-stitching-project-changes.mdx | 33 +++++++++++++++++++
 2 files changed, 35 insertions(+), 2 deletions(-)
 create mode 100644 packages/web/docs/src/pages/product-updates/2024-02-08-upcoming-stitching-project-changes.mdx

diff --git a/packages/web/docs/src/components/product-updates.tsx b/packages/web/docs/src/components/product-updates.tsx
index 33eeb1d1a..a5bdf162d 100644
--- a/packages/web/docs/src/components/product-updates.tsx
+++ b/packages/web/docs/src/components/product-updates.tsx
@@ -26,9 +26,9 @@ function ProductUpdateTeaser(props: Changelog) {
       <h3 className="text-lg font-semibold text-gray-900 dark:text-white">
         <Link href={props.route}>{props.title}</Link>
       </h3>
-      <p className="mb-4 text-base font-normal text-gray-500 dark:text-gray-400">
+      <div className="mb-4 mt-1 max-w-[600px] text-base font-normal leading-6 text-gray-500 dark:text-gray-400">
         {props.description}
-      </p>
+      </div>
     </li>
   );
 }
diff --git a/packages/web/docs/src/pages/product-updates/2024-02-08-upcoming-stitching-project-changes.mdx b/packages/web/docs/src/pages/product-updates/2024-02-08-upcoming-stitching-project-changes.mdx
new file mode 100644
index 000000000..2408433aa
--- /dev/null
+++ b/packages/web/docs/src/pages/product-updates/2024-02-08-upcoming-stitching-project-changes.mdx
@@ -0,0 +1,33 @@
+---
+title: Upcoming changes to schema composition for Schema Stitching projects
+description:
+  Due to stitching limitations we need to slightly alter the schema composition behaviour for more
+  predictable results.
+date: 2024-02-08
+authors: [laurin]
+---
+
+Due to limitations within the stitching implementation powered by
+[graphql-tools](https://github.com/ardatan/graphql-tools), we are going to slightly alter the
+behaviour of the schema composition for better predictability of the schema composition result.
+
+Currently, composition for schema stitching projects can lead to unexpected (seemingly unpredictable
+schema changes) appearing when publishing a service schema or running a schema check.
+
+The reason for this is that the composite schema output from the stitching composition
+implementation is affected by the order of the input (subgraph) schemas. Today, the input
+schemas/subgraphs for the composition are ordered by their creation date (publish date). This means
+that each publish/check (unless they are strictly run in the same order), can result in a different
+output schema.
+
+Some of you reached out to us because of this confusion and unpredictability.
+
+Due to these limitations, we decided to make subtle changes to the sorting of the input subgraph
+schemas in order to make the output composite schema more predictable.
+
+Starting on **20.04.2024,** the subgraphs will always be sorted alphanumerically by their name to
+ensure a stable input order across schema publishes and schema checks.
+
+We also recommend everyone that uses the graphql-tools stitching implementation to sort their
+schemas alphanumerically by their name in their gateway implementation. The Hive CDN will also serve
+the service list in that given order.