Merge pull request #1158 from apollographql/sb/rover-studio-changes

Studio docs changes for Rover GA

studio-docs/shared/register-cli.mdx

@@ -1,24 +1,20 @@
-1. <a href="https://www.apollographql.com/docs/devtools/cli/" target="_blank">Install the Apollo CLI</a> if you haven't yet.
+1. If you haven't yet:
+    *  <a href="https://www.apollographql.com/docs/rover/getting-started/" target="_blank">Install the Rover CLI.</a>
+    * <a href="https://www.apollographql.com/docs/rover/configuring/" target="_blank">Authenticate Rover</a> with Apollo Studio.
 
-2. Decide how you'll provide your server's schema to the Apollo CLI. The CLI can either:
+3. Decide how you'll provide your server's schema to Rover. You can either:
 
     * Use a `.gql` or `.graphql` file saved on your local machine, or
     * Perform an introspection query on your running server to fetch the schema
 
-2. Run the `apollo service:push` command, providing the following options (documented below):
+4. Run the `rover graph publish` command, providing your schema in one of the ways shown:
 
     ```bash
-    apollo service:push \
-      --localSchemaFile=./schema.gql \ # (or --endpoint)
-      --key=service:docs-example-graph:NYKgCqwfCyYPIm84WVXCdw
-      --graph=docs-example-graph \
-      --variant=local-development \
+    # Provide a local .graphql file path
+    rover graph publish my-graph@my-variant --schema ./schema.graphql
+
+    # Provide an introspection result via stdin
+    rover graph introspect http://localhost:4000 | rover graph publish my-graph@my-variant --schema -
     ```
 
-| Name | Description  |
-|---|---|
-| `--endpoint` | <p>The URL of the running service to perform an introspection query on.</p><p>**Provide this only if the CLI should obtain your schema via introspection.**</p> |
-| `--localSchemaFile` | <p>The path of the schema file to register.</p><p>**Provide this only if the CLI should obtain your schema via a local file.**</p> |
-| `--key` | <p>The graph API key that the CLI should use to authenticate with the schema registry.</p><p>By default, the CLI uses the value of the `APOLLO_KEY` environment variable.</p> |
-| `--graph` | The name of your graph in Apollo Studio (e.g., `docs-example-graph`) |
-| `--variant` | <p>The [variant of your graph](./org/graphs/#managing-variants) to register the schema with.</p><p>The default value is `current`.</p> |
+    As shown, the first positional argument you provide `rover graph publish` is a [graph ref](https://www.apollographql.com/docs/rover/conventions/#graph-refs), a string that specifies a particular variant of a particular graph in Studio.

studio-docs/shared/register-federated-cli.mdx

@@ -1,53 +1,46 @@
-In a federated architecture, each of your graph's [implementing services](https://www.apollographql.com/docs/federation/implementing-services/) uses the Apollo CLI to register its schema as a separate service **of the same graph**:
+In a federated architecture, each of your graph's [subgraphs](https://www.apollographql.com/docs/federation/subgraphs/) uses the Rover CLI to register its schema with Apollo:
 
 ```mermaid
-graph BT;
+graph LR;
   subgraph " "
   gateway([Gateway]);
-  serviceA[Products service];
-  serviceB[Reviews service];
-  serviceC[Inventory service];
+  serviceA[Products subgraph];
+  serviceB[Reviews subgraph];
+  serviceC[Inventory subgraph];
   end
   registry{{Apollo Schema Registry}};
   gateway --- serviceA & serviceB & serviceC;
-  serviceA -. --serviceName=Products  .-> registry;
-  serviceB -. --serviceName=Reviews  .-> registry;
-  serviceC -. --serviceName=Inventory  .-> registry;
+  serviceA & serviceB & serviceC -. rover subgraph publish  .-> registry;
   class registry secondary;
 ```
 
-First, <a href="https://www.apollographql.com/docs/devtools/cli/" target="_blank">install the Apollo CLI</a> if you haven't yet.
+If you haven't yet:
 
-Then, **do the following for each of your implementing services**:
+*  <a href="https://www.apollographql.com/docs/rover/getting-started/" target="_blank">Install the Rover CLI.</a>
+* <a href="https://www.apollographql.com/docs/rover/configuring/" target="_blank">Authenticate Rover</a> with Apollo Studio.
 
-1. Obtain the following values, which are required for the `apollo service:push` command:
+Then, **do the following for each of your subgraphs**:
 
-    * The URL that your federated gateway will use to communicate with the service (e.g., `http://products-graphql.svc.cluster.local:4001/`).
-    * The name that uniquely identifies the service within your graph (e.g., `products`).
-    * The service's schema. The Apollo CLI can either:
+1. Obtain the following values, which are required for the `rover subgraph publish` command:
+
+    * The name that uniquely identifies the subgraph within your graph (e.g., `products`).
+        * If you've already registered a particular subgraph at least once, you can get its name from your graph's **Schema > SDL** tab in Apollo Studio, or by running `rover subgraph list`.
+        * Otherwise, you set the subgraph's name the first time you register it. **Make sure the name is unique within your graph.**
+    * The URL that your gateway will use to communicate with the subgraph (e.g., `http://products-graphql.svc.cluster.local:4001/`).
+    * The service's schema. The Rover CLI can either:
         * Use a `.gql` or `.graphql` file saved on your local machine, or
         * Perform an introspection query on the running service to fetch the schema
 
-2. Run the `apollo service:push` command, providing the following options (documented below):
+2. Run the `rover subgraph publish` command, providing your schema in one of the ways shown:
 
     ```bash
-    apollo service:push \
-      --localSchemaFile=./schema.gql \ # (or --endpoint)
-      --key=service:docs-example-graph:NYKgCqwfCyYPIm84WVXCdw
-      --graph=docs-example-graph \
-      --variant=local-development \
-      --serviceName=products \
-      --serviceURL=http://products-graphql.svc.cluster.local:4001/
+    # Provide a local .graphql file path
+    rover subgraph publish my-graph@my-variant --name products --routing-url http://products-graphql.svc.cluster.local:4001/ --schema ./schema.graphql 
+
+    # Provide an introspection result via stdin
+    rover subgraph introspect http://localhost:4000 | rover subgraph publish my-graph@my-variant --name products --routing-url http://products-graphql.svc.cluster.local:4001/ --schema -
     ```
 
-| Name | Description  |
-|---|---|
-| `--endpoint` | <p>The URL of the running service to perform an introspection query on.</p><p>**Provide this only if the CLI should obtain your schema via introspection.**</p> |
-| `--localSchemaFile` | <p>The path of the schema file to register.</p><p>**Provide this only if the CLI should obtain your schema via a local file.**</p> |
-| `--key` | <p>The graph API key that the CLI should use to authenticate with the schema registry.</p><p>By default, the CLI uses the value of the `APOLLO_KEY` environment variable.</p> |
-| `--graph` | The name of your graph in Apollo Studio (e.g., `docs-example-graph`) |
-| `--variant` | <p>The [variant of your graph](https://www.apollographql.com/docs/studio/org/graphs/#managing-variants) to register the schema with.</p><p>The default value is `current`.</p> |
-| `--serviceName` | The service's unique name in your federated graph (e.g., `products`). |
-| `--serviceURL` | The URL that your federated gateway will use to communicate with the service. |
-
-As you register your service schemas, the schema registry attempts to **compose** their latest versions into a single **federated schema**. Whenever composition succeeds, your gateway can fetch the latest federated schema from the registry.
+As you register your subgraph schemas, the schema registry attempts to **compose** their latest versions into a single **supergraph schema**. Whenever composition succeeds, your gateway can fetch the latest supergraph schema from the registry.
+
+You can also fetch your latest supergraph schema with the `rover supergraph fetch` command, and it's available in Apollo Studio from your graph's **Schema > SDL** tab.

studio-docs/source/federated-graphs.mdx

@@ -95,7 +95,8 @@ Note that the `schema` object can’t be empty, so you need to add the `query` f
 
 #### Known `@contact` limitations
 
-- To provide the `@contact` directive to Apollo, you must register your schema using the `--localSchemaFile` option of [`apollo service push`](./schema/cli-registration/#registering-a-non-federated-schema). If you use the `--endpoint` option instead, directives are **not** included in the registered schema.
+- To provide the `@contact` directive to Apollo, you must register your schema by providing a local `.graphql` file as the `--schema` option of [`rover graph publish`](./schema/cli-registration/#registering-a-non-federated-schema).
+    * If you provide an introspection result to the command instead, directives are **not** included in the result.
 - Similarly, you cannot provide your `@contact` directive to Apollo via [schema reporting](./schema/schema-reporting/). This registration method also does not include directives.
 - If your subgraph doesn’t already have a `schema` object, you need to add one to use the `@contact` directive. The `schema` object cannot be empty, so you need to include at least one field in it (most commonly `query: Query`). If you do provide the `Query` type like this, it needs to include at least one field in your subgraph’s schema. If your subgraph’s `Query` type is empty, you need to add a dummy field for the SDL to be valid:
 

studio-docs/source/getting-started.mdx

@@ -80,7 +80,7 @@ Now whenever your server starts up, it automatically registers its schema with t
 
 <ExpansionPanel title="Any GraphQL server WITH Apollo Federation">
 
-> After you complete this step, complete the remaining steps in [Setting up managed federation](https://www.apollographql.com/docs/federation/managed-federation/setup/).
+> After you complete this step, you should also complete the remaining steps in [Setting up managed federation](https://www.apollographql.com/docs/federation/managed-federation/setup/).
 
   <RegisterFederatedCli />
 

studio-docs/source/github-integration.md

@@ -3,7 +3,7 @@ title: Connecting Apollo Studio to GitHub
 sidebar_title: Connecting to GitHub
 ---
 
-To make [schema checks](/schema-checks/) as easy to set up as possible, we've built an Apollo app for GitHub that provides status checks on pull requests when schema changes are proposed.
+To improve the convenience and helpfulness of [schema checks](/schema-checks/), we've built an Apollo app for GitHub that provides status checks on pull requests when schema changes are proposed.
 
 ![GitHub Status View](./img/schema-checks/github-check.png)
 
@@ -13,7 +13,7 @@ Go to [https://github.com/apps/apollo-studio](https://github.com/apps/apollo-stu
 
 ## Run a check on each commit
 
-Next, make sure your CI has a step to run the schema check command. This is accomplished by adding the `apollo service:check` command directly as a step in your CI. For CircleCI it could look something like this:
+Next, make sure your CI has a step to run the schema check command. This is accomplished by adding the `rover graph check` command directly as a step in your CI. For CircleCI it could look something like this:
 
 ### CircleCI
 
@@ -23,14 +23,14 @@ version: 2
 jobs:
   build:
     docker:
-      - image: circleci/node:8
+      - image: cimg/node:16.0.0
 
     steps:
       - checkout
 
       - run: npm install
       # CircleCI needs global installs to be sudo
-      - run: sudo npm install --global apollo
+      - run: sudo npm install --global @apollo/rover
 
       # Start the GraphQL server.  If a different command is used to
       # start the server, use it in place of `npm start` here.
@@ -43,16 +43,15 @@ jobs:
       # commands against it
       - run: sleep 5
 
-      # This will authenticate using the `APOLLO_KEY` environment
-      # variable. If the GraphQL server is available elsewhere than
-      # http://localhost:4000/graphql, set it with `--endpoint=<URL>`.
-      - run: apollo service:check --graph=example-graph --variant=main
+      # Rover authenticates using the `APOLLO_KEY` environment
+      # variable.
+      - run: rover graph check my-graph@my-variant --schema ./schema.graphql
 
       # When running on the 'main' branch, publish the latest version
       # of the schema to Apollo Studio.
       - run: |
           if [ "${CIRCLE_BRANCH}" == "main" ]; then
-            apollo service:push
+            rover graph publish my-graph@my-variant --schema ./schema.graphql
           fi
 ```
 
@@ -85,14 +84,14 @@ jobs:
           # Apollo Key is supplied as an env var from github secrets
           APOLLO_KEY: ${{ secrets.APOLLO_KEY }}
         run: |
-          npx apollo service:check \
+          rover graph check my-graph@my-variant --schema ./schema.graphql  \
             --branch=${GITHUB_REF#refs/heads/} \
             --author=$GITHUB_ACTOR \
             --commitId=$(git rev-parse $GITHUB_SHA^2)
 ```
 
-> **Note:** Your `apollo service:check` command needs a source from which to fetch your schema. This is most commonly provided as a URL to a running server (with introspection enabled), but can also be provided as a path to a file with your schema in it.
+> **Note:** The `rover graph check` requires your graph's schema. You can provide it to the `--schema` option via a local file, or you can [pass an introspection result via stdin](https://www.apollographql.com/docs/rover/graphs/#checking-schema-changes).
 
-The `apollo schema:check` command checks for differences in your schema between what's on your current branch and the last version you uploaded to Apollo Studio. If you've removed or changed any types or fields, it will validate that those changes won't break any of the queries that your clients have made recently. If your changes do break any queries, the check will fail.
+The `rover graph check` command checks for differences in your schema between what's on your current branch and the last version you uploaded to Apollo Studio. If you've removed or changed any types or fields, the command checks whether those changes break any queries that your clients have made recently. If your changes do break any queries, the check fails.
 
-Because you installed the Apollo Studio app on GitHub, the check you've added will show up as a line in your GitHub checks list. If there are changes in your schema you'll be able to review them by clicking the "Details" link. By enabling schema checks in your continuous integration workflow (such as CircleCI), you're alerting developers of any potential problems directly in their pull requests, thereby giving them critical feedback where it's most useful.
+Because you installed the Apollo Studio app on GitHub, the check you've added shows up as a line in your GitHub checks list. If there are changes in your schema, you can review them by clicking the "Details" link. By enabling schema checks in your continuous integration workflow (such as CircleCI), you're alerting developers of any potential problems directly in their pull requests, thereby giving them critical feedback where it's most useful.

studio-docs/source/org/members.mdx

@@ -56,7 +56,7 @@ When `Contributors` in an organization create a new graph, they are automaticall
 | Manage Explorer settings (URL, etc)                             |     ✓     |      ✓      |  Non-[protected](./graphs/#protected-variants-enterprise-only) variants only      |          |          |
 | Create [Deployed Graphs](/org/graphs/)                          |     ✓     |      ✓      |      ✓      |          |          |
 | Run [schema checks](../schema-checks)                                               |     ✓     |      ✓      |      ✓      |    ✓     |          |
-| See the schemas of implementing services in federated graphs    |     ✓     |      ✓      |      ✓      |    ✓     |          |
+| See the schemas of subgraphs in federated graphs    |     ✓     |      ✓      |      ✓      |    ✓     |          |
 | View graph usage metrics and traces                             |     ✓     |      ✓      |      ✓      |    ✓     |          |
 | Create [Development Graphs](/dev-graphs/)                       |     ✓     |      ✓      |      ✓      |    ✓     |     ✓    |
 | View graph schemas and changelogs                               |     ✓     |      ✓      |      ✓      |    ✓     |    ✓     |
@@ -95,13 +95,13 @@ A few operations aren't listed in the table above because they are *only* suppor
 - Reporting usage (traces and performance metrics). This requires a `Graph Admin` key, or a `Contributor` key if the variant is not protected.
 - [Registering operations](../operation-registry/). This requires a `Graph Admin` key.
 
-> Before January 2021, graph keys did not have roles. Keys created before that date (which are shown as `Legacy Admin` keys) can perform the following operations:
+> Before January 2021, graph keys did not have roles. Keys created before that date (shown as `Legacy Admin` keys) can perform the following operations:
 >
 > - Create new variants
 > - Run schema checks
 > - View and manage graph API keys
 > - Push schemas to a graph
-> - See the schemas of implementing services in federated graphs
+> - See the schemas of subgraphs in federated graphs
 > - View graph schemas and changelogs
 > - Modify schema checks configuration
 

studio-docs/source/schema/cli-registration.mdx

@@ -1,16 +1,15 @@
 ---
-title: Schema registration via the Apollo CLI
-sidebar_title: Using the Apollo CLI
+title: Schema registration via the Rover CLI
+sidebar_title: Using the Rover CLI
 ---
 
 import ProjectConfigPanel from "gatsby-theme-apollo-docs/shared/project-config-panel.mdx";
 import RegisterCli from '../../shared/register-cli.mdx';
 import RegisterFederatedCli from '../../shared/register-federated-cli.mdx'
 
+If you're using a GraphQL server that doesn't support [schema reporting](./schema-reporting/), you can register your schema via the [Rover CLI](https://www.apollographql.com/docs/rover/).
 
-If you're using an earlier version of Apollo Server or another GraphQL server that doesn't support [schema reporting](./schema-reporting/), you can register your schema via the [Apollo CLI](https://www.apollographql.com/docs/devtools/cli/).
-
-> **Do not use both schema reporting and the Apollo CLI to register schemas for the same graph.** Doing so can cause you to register "no-op" schema changes that are semantically identical but cosmetically different. For example, automatic registration preserves a schema's comments and directives, whereas manual registration does not.
+> **Do not use both schema reporting and Rover to register schemas for the same graph.** Doing so can cause you to register "no-op" schema changes that are semantically identical but cosmetically different. For example, schema reporting preserves a schema's comments and directives, whereas CLI registration does not.
 
 ## Registering a non-federated schema
 
@@ -39,7 +38,7 @@ jobs:
 
       - run: npm install
       # CircleCI needs global installs to be sudo
-      - run: sudo npm install --global apollo
+      - run: sudo npm install --global @apollo/rover
 
       # Start the GraphQL server.  If a different command is used to
       # start the server, use it in place of `npm start` here.
@@ -56,6 +55,6 @@ jobs:
       # of the schema to Apollo Studio.
       - run: |
           if [ "${CIRCLE_BRANCH}" == "master" ]; then
-            apollo service:push --variant=master
+            rover graph publish my-graph@my-variant --schema ./schema.graphql
           fi
 ```

studio-docs/source/schema/schema-reporting.mdx

@@ -1,6 +1,6 @@
 ---
 title: Schema registration via schema reporting
-sidebar_title: Using schema reporting (recommended)
+sidebar_title: Using schema reporting
 ---
 
 import ObtainGraphApiKey from "../../shared/obtain-graph-api-key";