docs: add <MinVersion> to federated directives (#2928)

This PR adds `<MinVersion >` to all [federated directives](https://www.apollographql.com/docs/federation/federated-types/federated-directives). This PR also creates and uses a shared `<EnterpriseDirective >`component and edits the `<ProgressiveOverrideEnterprise>` component to remove the required version. (Now handled by `<MinVersion>`.) --------- Co-authored-by: Edward Huang <[email protected]>
apollographql · Feb 2, 2024 · f9662c7 · f9662c7
1 parent 555d60d
commit f9662c7
Show file tree

Hide file tree

Showing 4 changed files with 75 additions and 19 deletions.
diff --git a/docs/shared/enterprise-directive.mdx b/docs/shared/enterprise-directive.mdx
@@ -0,0 +1,5 @@
+<EnterpriseFeature>
+
+This directive is an [Enterprise feature](/router/enterprise-features) of the Apollo Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). If your organization doesn't have an Enterprise plan, you can test it out by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials).
+
+</EnterpriseFeature>
diff --git a/docs/shared/progressive-override-enterprise.mdx b/docs/shared/progressive-override-enterprise.mdx
@@ -1,7 +1,5 @@
 <EnterpriseFeature>
 
-Progressive `@override` is an [Enterprise feature](/router/enterprise-features) of the Apollo Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). It also requires Apollo Federation v2.7 or later.
-
-If your organization _doesn't_ currently have an Enterprise plan, you can test out this functionality by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials).
+Progressive `@override` is an [Enterprise feature](/router/enterprise-features) of the Apollo Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). If your organization doesn't have an Enterprise plan, you can test it out by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials).
 
 </EnterpriseFeature>
diff --git a/docs/source/entities-advanced.mdx b/docs/source/entities-advanced.mdx
@@ -398,8 +398,12 @@ Because the router is already _ignoring_ `Bill.amount` in the Payments subgraph
 
 After we deploy the Billing subgraph and publish this final schema change, we're done. We've migrated `Bill.amount` to the Billing subgraph with zero downtime.
 
+<MinVersion version="2.7">
+
 ### Incremental migration with progressive `@override`
 
+</MinVersion>
+
 You can migrate between subgraphs gradually with progressive `@override`.
 
 <ProgressiveOverrideEnterprise/>

diff --git a/docs/source/federated-types/federated-directives.mdx b/docs/source/federated-types/federated-directives.mdx
@@ -3,6 +3,7 @@ title: Federation-specific GraphQL directives
 ---
 
 import ProgressiveOverrideEnterprise from '../../shared/progressive-override-enterprise.mdx';
+import EnterpriseDirective from '../../shared/enterprise-directive.mdx';
 
 Apollo Federation defines a collection of **directives** that you use in your subgraph schemas to enable certain features.
 
@@ -70,9 +71,12 @@ type Book @fed__shareable {
 
 As shown, custom namespace prefixes _also_ end in two underscores.
 
+<MinVersion version="2.0">
 
 ### The `@link` directive
 
+</MinVersion>
+
 ```graphql
 directive @link(
   url: String!,
@@ -88,8 +92,12 @@ For more information on `@link`, see the [official spec](https://specs.apollo.de
 
 ## Managing types
 
+<MinVersion version="1.0">
+
 ### `@key`
 
+</MinVersion>
+
 ```graphql
 directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE
 ```
@@ -190,8 +198,12 @@ During composition, the fields of every `@interfaceObject` are added both to the
 
 > [Learn more about entity interfaces.](./interfaces/)
 
+<MinVersion version="1.0">
+
 ### `@extends`
 
+</MinVersion>
+
 ```graphql
 directive @extends on OBJECT | INTERFACE
 ```
@@ -208,8 +220,12 @@ This directive is for use with GraphQL subgraph libraries that do _not_ support
 
 ## Managing shared fields
 
+<MinVersion version="2.0">
+
 ### `@shareable`
 
+</MinVersion>
+
 ```graphql
 directive @shareable on FIELD_DEFINITION | OBJECT
 ```
@@ -242,8 +258,12 @@ See also [Value types in Apollo Federation](./sharing-types/) and [Resolving ano
 
 > The `@shareable` directive is about indicating when an object field can be resolved by multiple subgraphs. As interface fields are not directly resolved (their implementation is), `@shareable` is not meaningful on an interface field and is not allowed (at least since federation 2.2; earlier versions of federation 2 mistakenly ignored `@shareable` on interface fields).
 
+<MinVersion version="2.0">
+
 ### `@inaccessible`
 
+</MinVersion>
+
 ```graphql
 directive @inaccessible on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
 ```
@@ -287,8 +307,12 @@ An `@inaccessible` field or type is _not_ omitted from the _supergraph_ schema,
 
 For more information, see [Using `@inaccessible`](./sharing-types/#using-inaccessible).
 
+<MinVersion version="2.0">
+
 ### `@override`
 
+</MinVersion>
+
 ```graphql
 directive @override(from: String!) on FIELD_DEFINITION
 ```
@@ -323,8 +347,12 @@ Only one subgraph can `@override` any given field. If multiple subgraphs attempt
 
 For more information, see [Migrating entities and fields](../entities-advanced/#migrating-entities-and-fields).
 
+<MinVersion version="2.7">
+
 #### Progressive `@override`
 
+</MinVersion>
+
 <ProgressiveOverrideEnterprise/>
 
 Rolling out any change to a production subgraph, including field migration, risks degrading the performance of your graph. Rerouting all traffic from one subgraph to another _all at once_ could overload the overriding subgraph.
@@ -368,13 +396,15 @@ To learn more, see the [Incremental migration with `@override`](../entities-adva
 ##### `label`
 
 `String`
+
 </td>
 <td>
 
-> ⚠️ **This argument is available in Apollo Federation 2.7 and later.**
-> **It is an [Enterprise feature](/router/enterprise-features) of the Apollo Router** and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/).<br/>
->
-> If your organization _doesn't_ currently have an Enterprise plan, you can test out this functionality by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials).
+<EnterpriseFeature>
+
+This argument is available in Apollo Federation 2.7 and later. It is an [Enterprise feature](/router/enterprise-features) of the Apollo Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). You can test it out by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials).
+
+</EnterpriseFeature>
 
 **Optional.** A string of arbitrary arguments. Supported in this release:
 - `percent(<percent-value>)` - The percentage of traffic for the field that's resolved by this subgraph. The remaining percentage is resolved by the other ([from](#from)) subgraph. To learn more, see [Incremental migration with `@override`](../entities-advanced/#incremental-migration-with-override).
@@ -387,12 +417,14 @@ To learn more, see the [Incremental migration with `@override`](../entities-adva
 
 ## Controlling access
 
+<MinVersion version="2.5">
+
 ### `@authenticated`
 
-> ⚠️ **This directive is available in Apollo Federation 2.5 and later.**
-> **It is an [Enterprise feature](/router/enterprise-features) of the Apollo Router** and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/).<br/>
->
-> If your organization _doesn't_ currently have an Enterprise plan, you can test out this functionality by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials).
+</MinVersion>
+
+<EnterpriseDirective />
+
 
 ```graphql
 directive @authenticated on
@@ -405,12 +437,13 @@ directive @authenticated on
 
 Indicates to composition that the target element is accessible only to the authenticated supergraph users. For more granular access control, see the [`@requiresScopes`](#requiresScopes) directive below. Refer to the [Apollo Router article](/router/configuration/authorization#authenticated) for additional details.
 
+<MinVersion version="2.5">
+
 ### `@requiresScopes`
 
-> ⚠️ **This directive is available in Apollo Federation 2.5 and later.**
-> **It is an [Enterprise feature](/router/enterprise-features) of the Apollo Router** and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/).<br/>
->
-> If your organization _doesn't_ currently have an Enterprise plan, you can test out this functionality by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials).
+</MinVersion>
+
+<EnterpriseDirective />
 
 ```graphql
 directive @requiresScopes(scopes: [[federation__Scope!]!]!) on
@@ -453,12 +486,13 @@ Indicates to composition that the target element is accessible only to the authe
 </tbody>
 </table>
 
+<MinVersion version="2.6">
+
 ### `@policy`
 
-> ⚠️ **This directive is available in Apollo Federation 2.6 and later.**
-> **It is an [Enterprise feature](/router/enterprise-features) of the Apollo Router** and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/).<br/>
->
-> If your organization _doesn't_ currently have an Enterprise plan, you can test out this functionality by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials).
+</MinVersion>
+
+<EnterpriseDirective />
 
 ```graphql
 directive @policy(policies: [[federation__Policy!]!]!) on
@@ -503,8 +537,12 @@ Indicates to composition that the target element is restricted based on authoriz
 
 ## Referencing external fields
 
+<MinVersion version="1.0">
+
 ### `@external`
 
+</MinVersion>
+
 ```graphql
 directive @external on FIELD_DEFINITION | OBJECT
 ```
@@ -537,9 +575,12 @@ type Position @external {
 }
 ```
 
+<MinVersion version="1.0">
 
 ### `@provides`
 
+</MinVersion>
+
 ```graphql
 directive @provides(fields: FieldSet!) on FIELD_DEFINITION
 ```
@@ -611,8 +652,12 @@ Examples:
 </tbody>
 </table>
 
+<MinVersion version="1.0">
+
 ### `@requires`
 
+</MinVersion>
+
 ```graphql
 directive @requires(fields: FieldSet!) on FIELD_DEFINITION
 ```
@@ -672,8 +717,12 @@ Examples:
 
 ## Applying metadata
 
+<MinVersion version="1.1">
+
 ### `@tag`
 
+</MinVersion>
+
 ```graphql
 directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
 ```