From 71224f45a99e6efd9ed7e2d1cdb66fac189c5410 Mon Sep 17 00:00:00 2001
From: Shane Myrick <shane@apollographql.com>
Date: Tue, 5 Dec 2023 11:22:33 -0800
Subject: [PATCH] docs: Update backward-compatibility with @provides info
 (#2837)

Add info about `@provides` backwards compatibility

---------

Co-authored-by: Maria Elisabeth Schreiber <maria.schreiber@apollographql.com>
---
 .../federation-2/backward-compatibility.mdx   | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/docs/source/federation-2/backward-compatibility.mdx b/docs/source/federation-2/backward-compatibility.mdx
index 29baccb75..1f7e01d30 100644
--- a/docs/source/federation-2/backward-compatibility.mdx
+++ b/docs/source/federation-2/backward-compatibility.mdx
@@ -130,6 +130,54 @@ type ProductDimensions {
 
 This `@requires` directive should _break_ composition because it depends on subfields of `ProductDimensions` that _don't exist_ (`length` and `depth`).
 
+#### Invalid `@provides` directives
+
+A subgraph can annotate an entity field with the [`@provides` directive](/federation/federated-types/federated-directives/#provides) to indicate that the subgraph can resolve entity fields normally marked as `@external` on its own.
+
+<p style="margin-bottom: 0">✅</p>
+
+```graphql title="Subgraph A"
+type Product @key(fields: "id") {
+  id: ID!
+  info: ProductInfo @external
+}
+
+type ProductInfo {
+  name: String! @external
+  inStock: Boolean! @external
+}
+
+type Query {
+  outOfStockProducts: [Product!]! @provides(fields: "info { name }")
+  discontinuedProducts: [Product!]!
+}
+```
+
+In the above example, Subgraph A can resolve the `Product.info.name` field  when accessed through the `outOfStockProducts` query. Any other path to `Product.info.name` results in an additional subgraph call.
+
+Federation 1 _incorrectly_ allows `@provides` usage like the following:
+
+<p style="margin-bottom: 0">❌</p>
+
+```graphql title="Subgraph A"
+type Product @key(fields: "id") {
+  id: ID!
+  info: ProductInfo @external
+}
+
+type ProductInfo {
+  name: String! @external
+  inStock: Boolean! @external
+}
+
+type Query {
+  outOfStockProducts: [Product!]! @provides(fields: "info")
+  discontinuedProducts: [Product!]!
+}
+```
+
+The above `@provides` directives usage should _break_ composition because it does not specify which subfields of `ProductInfo` it can resolve. This is correctly caught and surfaced as an error in Federation v2 but Federation v1 incorrectly allows this usage.
+
 </ExpansionPanel>