apollographql
diff --git a/‎docs/source/schema-design/federated-schemas/reference/backward-compatibility.mdx‎
Lines changed: 203 additions & 0 deletions b/‎docs/source/schema-design/federated-schemas/reference/backward-compatibility.mdx‎
Lines changed: 203 additions & 0 deletions
@@ -0,0 +1,203 @@
+---
+title: Backward Compatibility in Apollo Federation 2
+subtitle: Navigating the transition from Apollo Federation 1 to Federation 2
+description: Frequently asked questions when transitioning from Apollo Federation 1 to Federation 2.
+---
+
+## Is official support ending for `@apollo/gateway` v0.x?
+
+Yes. `@apollo/gateway` v0.x was officially deprecated as of 15 November 2022 and reached end-of-life on 22 September 2023. `@apollo/gateway` v2.x remains fully supported.
+
+[Learn more about deprecation and end-of-life.](https://www.apollographql.com/docs/resources/product-launch-stages#stages-for-discontinuing-support)
+
+## Do I need to modify my subgraph schemas to use Federation 2?
+
+Eventually. The process of [moving to Federation 2](/graphos/reference/migration/to-federation-version-2/) has three steps:
+
+1. Upgrade your gateway to support Federation 2 (we recommend [moving to the GraphOS Router](/graphos/reference/migration/from-gateway/)).
+2. Begin composing your supergraph schema with Federation 2 composition logic.
+3. Update your individual subgraphs to use Federation 2 features and directives.
+
+Steps 1 and 2 usually require no changes to your subgraph schemas. Schemas that do require changes are schemas that should cause certain composition errors that Federation 1 fails to detect ([see below.](#breaking-changes)).
+
+Step 3 does require some changes to your subgraph schemas, described [here](/graphos/reference/migration/to-federation-version-2/#step-3-update-individual-subgraphs).
+
+
+### Breaking changes
+
+As mentioned above, the following Federation 1 examples should produce composition errors, but they aren't detected. If your subgraph schemas include syntax that matches any of these, you need to update those schemas before moving to Federation 2.
+
+<ExpansionPanel title="See breaking changes">
+
+#### Invalid `@key` directives
+
+An entity's `@key` consists of one or more of the entity's own `fields`. If any of these fields have subfields, the `@key` must also include at least one of those subfields:
+
+<p style="margin-bottom: 0">✅</p>
+
+```graphql {1}
+type User @key(fields: "id organization { id }") {
+ id: ID!
+ organization: Organization!
+}
+
+type Organization {
+ id: ID!
+ name: String!
+}
+```
+
+In this example, the `User`'s key fields are `User.id` and `User.organization.id`.
+
+Federation 1 composition incorrectly allows a `@key` such as the following:
+
+<p style="margin-bottom: 0">❌</p>
+
+```graphql {1}
+type User @key(fields: "id organization") {
+ id: ID!
+ organization: Organization!
+}
+
+type Organization {
+ id: ID!
+ name: String!
+}
+```
+
+This `@key` should break composition because it doesn't include at least one subfield of `Organization`.
+
+#### Invalid `@requires` directives
+
+A subgraph can mark an entity field with the [`@requires` directive](https://www.apollographql.com/docs/federation/entities/#extending-an-entity-with-computed-fields-advanced) to indicate that it depends on fields and subfields from another subgraph:
+
+<p style="margin-bottom: 0">✅</p>
+
+```graphql title="Subgraph A"
+type Product @key(fields:"sku") {
+  sku: ID!
+  dimensions: ProductDimensions!
+}
+
+type ProductDimensions {
+  size: Int!
+  weight: Int!
+}
+```
+
+```graphql {4} title="Subgraph B"
+extend type Product @key(fields:"sku") {
+  sku: ID! @external
+  dimensions: ProductDimensions! @external
+  shippingEstimate: Int! @requires(fields: "dimensions { size weight }")
+}
+
+type ProductDimensions {
+  size: Int!
+  weight: Int!
+}
+```
+
+In this example, Subgraph B's `shippingEstimate` field depends on the `dimensions.size` and `dimensions.weight` fields of Subgraph A.
+
+Federation 1 incorrectly allows a `@requires` directive such as the following:
+
+<p style="margin-bottom: 0">❌</p>
+
+```graphql title="Subgraph A"
+type Product @key(fields:"sku") {
+  sku: ID!
+  dimensions: ProductDimensions!
+}
+
+type ProductDimensions {
+  size: Int!
+  weight: Int!
+}
+```
+
+```graphql {4} title="Subgraph B"
+extend type Product @key(fields:"sku") {
+  sku: ID! @external
+  dimensions: ProductDimensions! @external
+  shippingEstimate: Int! @requires(fields: "dimensions { length depth }")
+}
+
+type ProductDimensions {
+  size: Int!
+  weight: Int!
+}
+```
+
+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>
+
+
+## Can Federation 1 compose my Federation 2 subgraph schemas?
+
+No, not after you [convert at least one subgraph schema](#do-i-need-to-modify-my-subgraph-schemas-to-use-federation-2) to a true Federation 2 schema.
+
+Federation 2 provides more flexible composition rules compared to Federation 1. After you modify your subgraph schemas to take advantage of this flexibility, your graph will no longer compose with Federation 1. You need to revert these changes to move back to Federation 1.
+
+## Does `@apollo/gateway` v2 support Federation 1?
+
+Yes. If you want, you can update your gateway's `@apollo/gateway` library to its latest `2.x` version before you're ready to [move your graph to Federation 2](/graphos/reference/migration/to-federation-version-2/).
+
+Your plugins and customizations for `@apollo/gateway` `0.x` will continue to work as expected in `@apollo/gateway` `2.x`.
+
+## Compatibility table
+
+| Router/Gateway version | Federation 1<br/>Composition | Federation 2<br/>Composition |
+|-|--------------|--------------|
+| Apollo Router Core v1.x | 🟢 | 🟢 |
+| `@apollo/gateway` v2.x | 🟢 | 🟢 |
+| `@apollo/gateway` v0.x (deprecated) | 🟢 | ❌ |