chore(docs): update for dev rewrite #2333

aaronArinder · 2025-01-03T20:13:55Z

⚠️ ⚠️ ⚠️ ACH TUNG: merging to main deploys docs, so don't merge this until we've released 0.27

svc-apollo-docs · 2025-01-03T20:13:59Z

✅ Docs Preview Ready

Configuration

{
  "repoOverrides": {
    "apollographql/rover@main": {
      "remote": {
        "owner": "apollographql",
        "repo": "rover",
        "branch": "aaron/BGS-136/docs"
      }
    }
  }
}

Name	Link
Commit	`5d7e789`
Preview	https://www.apollographql.com/docs/deploy-preview/77cae231c9b3097c74f9
Build ID	77cae231c9b3097c74f9
File Changes	0 new, 1 changed, 0 removed `* (developer-tools)/rover/commands/dev.mdx`
Pages	1

1 pages published. Build will be available for 30 days.

Meschreiber

TYSM for taking the first stab at this! I left some clarifying questions and will push a copyedit on top of this once those are clear.

The two main changes I plan to make in the copyedit:

A little restructuring—I think it's a little confusing to start mention subgraph(s) plural before the ### Starting a session with multiple subgraph section. Additionally, I think we want to prioritize/recommend using the config file, perhaps even if they're only starting with one subgraph. (Lends itself to adding more on.) LMK if you agree and then I'll restructure a little
This is a significant enough change that I'd like to add a <Note> about the way things used to be with a link to the changelog.

Meschreiber · 2025-01-06T16:32:05Z

docs/source/commands/dev.mdx

@@ -47,16 +47,15 @@ You don't have to provide a locally running subgraph. You can point to any Graph

 When you start your first `rover dev` process:

-1. Rover obtains the subgraph schema you provide via either introspection or file path.
-2. Rover composes a [supergraph schema](/federation/federated-types/overview/#supergraph-schema) from the subgraph schema.
+1. Rover obtains the subgraph schema(s) you provide via either introspection or the [supergraph config file](./supergraphs#yaml-configuration-file).


Does the removal of file path mean you can no longer pass in the --schema argument to provide a subgraph schema or are we conflating introspection/file path in this sentence?

Meschreiber · 2025-01-06T16:41:19Z

docs/source/commands/dev.mdx


 ### Starting a session with multiple subgraphs

-If you have a standard set of subgraphs that you're always developing with, you can create a [supergraph config file](./supergraphs#yaml-configuration-file) to add all of them to your local router session with a single `rover dev` command.
+If you work with a standard set of subgraphs, you can create a [supergraph config file](./supergraphs#yaml-configuration-file) and add all of them to your local router session with a single `rover dev` command.


Much more readible, thank you 🙇‍♀️

Meschreiber · 2025-01-06T16:43:35Z

docs/source/commands/dev.mdx

-After you start a router session with your first `rover dev` command, you can then add other subgraphs to that same session.
-
-To add a subgraph, open a new terminal window and run `rover dev` again, this time providing the details of the subgraph to add. For example, this command adds a `users` subgraph:
+Or by passing the `--federation-version` option. If both are provided, the CLI option takes precedence.


I don't think this is documented yet, is this a new option for the rover dev command?

Meschreiber · 2025-01-06T16:44:27Z

docs/source/commands/dev.mdx

-## Removing a subgraph
-
-If you stop a secondary `rover dev` process (by pressing `CTRL+C`), its associated router session recomposes its supergraph schema without the corresponding subgraph and reloads the router.
+While running `rover dev`, it's possible to add, remove, and update subgraphs by updating the `supergraph.yaml` file. If you're not using a `supergraph.yaml` file, but are using introspection to get the subgraph's schema, changes to that subgraph will be reflected in the router without the need to write a `supergraph.yaml` file.


Suggested change

While running `rover dev`, it's possible to add, remove, and update subgraphs by updating the `supergraph.yaml` file. If you're not using a `supergraph.yaml` file, but are using introspection to get the subgraph's schema, changes to that subgraph will be reflected in the router without the need to write a `supergraph.yaml` file.

While running `rover dev`, you can add, remove, and update subgraphs via the `supergraph.yaml` file. If you're not using a `supergraph.yaml` file and using introspection to get a subgraph's schema, changes to that subgraph will be reflected in the router without the need to write a `supergraph.yaml` file.

Out of curiosity: can you use introspection and the config file together?

Meschreiber · 2025-01-06T16:48:16Z

docs/source/commands/dev.mdx

 The ELv2-licensed plugins, `supergraph` (built from [this source](https://github.com/apollographql/federation-rs)) and `router` (built from [this source](https://github.com/apollographql/router)) are installed to `~/.rover/bin` if you installed with the `curl | sh` installer, and to `./node_modules/.bin/` if you installed with npm.

 ## Versioning

-By default, `rover dev` uses a recent version of the router and composition to use for you. This is currently configured in the Rover GitHub repo, however, you can override these by setting the environment variables `APOLLO_ROVER_DEV_COMPOSITION_VERSION=2.0.0` and/or `APOLLO_ROVER_DEV_ROUTER_VERSION=1.0.0`. By default, `rover dev` will always use a composition library with a major version of v2, and a router with a major version of v1. If you already have the plugins installed, you can pass `--skip-update` to `rover dev` in order to keep the plugins at the same version.
+By default, `rover dev` uses the latest version of the router and composition to use for you. This is currently configured in the Rover GitHub repo, however, you can override either of these by setting the environment variables `APOLLO_ROVER_DEV_COMPOSITION_VERSION=2.0.0` and `APOLLO_ROVER_DEV_ROUTER_VERSION=1.0.0`.


Is the skip-update option still available? We might need to document it here or elsewhere since I think this is the only mention of it.

monkpow · 2025-01-06T21:49:18Z

docs/source/commands/dev.mdx

-
-After you start a local router session with your first `rover dev` process, you can run additional `rover dev` processes to [add subgraphs to the session.](#adding-a-subgraph-to-a-session)
+4. Rover starts watching the provided subgraph schema(s) for changes, recomposing the supergraph schema whenever it detects a change. This automatically reloads the router.
+5. If provided via the `--router-config` CLI option, Rover starts watching the router config for changes, automatically reloading the router whenever it detects a change.


Nit, I like "when" over "if" here.

When provided a --router-config, Rover watches the router config for changes, automatically reloading the router whenever it detects a change

monkpow · 2025-01-06T21:51:01Z

docs/source/commands/dev.mdx

@@ -87,7 +86,7 @@ If you do, a router session starts with one of the subgraphs listed, then adds t

 Providing a `supergraph.yaml` file also enables you to take advantage of [other config options](./supergraphs#yaml-configuration-file), such as `introspection_headers`.

-If you start your session with a config file, you can still [add other subgraphs individually](#adding-a-subgraph-to-a-session). However, you can't provide another config file.
+Rover watches the `supergraph.yaml` for changes, allowing you to add, remove, or update subgraphs, making those changes available to the router instance. Only one config file may be used at a time for the `rover dev` session.


do we watch supergraph.yaml or is this a sample value? I think it might be clearer to say

Rover watches the value provided to --supergraph-config...

monkpow · 2025-01-06T21:53:26Z

docs/source/commands/dev.mdx

 You can view a variant's subgraphs, including their routing URLs and schemas, on the variant's **Subgraphs** page in Studio.
+You may also use remote subgraphs in your `supergraph.yaml`. See the `actors` subgraph in the `supergraph.yaml` example above for the syntax.


Eh, I see why you're using supergraph.yaml here, but I think it might be clearer to use --supergraph-config. I'll agree if your instincts lead you to keep this as is.

monkpow

I made a few editorial (optional, selectable) comments about stylistic notions. Overall, this does the job of updating to the new paradigm and improves a few phrases for clarity along the way.

aaronArinder requested review from a team as code owners January 3, 2025 20:13

aaronArinder force-pushed the aaron/BGS-136/docs branch from 020ce86 to f5a76a6 Compare January 3, 2025 20:14

Meschreiber approved these changes Jan 3, 2025

View reviewed changes

Meschreiber self-requested a review January 3, 2025 20:34

aaronArinder force-pushed the aaron/BGS-136/docs branch 2 times, most recently from 595fcd5 to f1cb398 Compare January 6, 2025 14:28

aaronArinder enabled auto-merge (squash) January 6, 2025 14:33

aaronArinder force-pushed the aaron/BGS-136/docs branch from f1cb398 to a76de4f Compare January 6, 2025 14:47

aaronArinder disabled auto-merge January 6, 2025 15:54

Meschreiber reviewed Jan 6, 2025

View reviewed changes

monkpow reviewed Jan 6, 2025

View reviewed changes

monkpow approved these changes Jan 6, 2025

View reviewed changes

aaronArinder added 2 commits January 6, 2025 17:21

chore(docs): update for dev rewrite

8f8723b

fix(typo)

5d7e789

aaronArinder force-pushed the aaron/BGS-136/docs branch from de7434b to 5d7e789 Compare January 6, 2025 22:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(docs): update for dev rewrite #2333

chore(docs): update for dev rewrite #2333

aaronArinder commented Jan 3, 2025 •

edited

Loading

svc-apollo-docs commented Jan 3, 2025 •

edited

Loading

Meschreiber left a comment

Meschreiber Jan 6, 2025

Meschreiber Jan 6, 2025

Meschreiber Jan 6, 2025

Meschreiber Jan 6, 2025

Meschreiber Jan 6, 2025

Meschreiber Jan 6, 2025

monkpow Jan 6, 2025

monkpow Jan 6, 2025 •

edited

Loading

monkpow Jan 6, 2025

monkpow left a comment

	While running `rover dev`, it's possible to add, remove, and update subgraphs by updating the `supergraph.yaml` file. If you're not using a `supergraph.yaml` file, but are using introspection to get the subgraph's schema, changes to that subgraph will be reflected in the router without the need to write a `supergraph.yaml` file.
	While running `rover dev`, you can add, remove, and update subgraphs via the `supergraph.yaml` file. If you're not using a `supergraph.yaml` file and using introspection to get a subgraph's schema, changes to that subgraph will be reflected in the router without the need to write a `supergraph.yaml` file.

		You can view a variant's subgraphs, including their routing URLs and schemas, on the variant's Subgraphs page in Studio.
		You may also use remote subgraphs in your `supergraph.yaml`. See the `actors` subgraph in the `supergraph.yaml` example above for the syntax.

chore(docs): update for dev rewrite #2333

Are you sure you want to change the base?

chore(docs): update for dev rewrite #2333

Conversation

aaronArinder commented Jan 3, 2025 • edited Loading

svc-apollo-docs commented Jan 3, 2025 • edited Loading

✅ Docs Preview Ready

Meschreiber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

monkpow Jan 6, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

monkpow left a comment

Choose a reason for hiding this comment

aaronArinder commented Jan 3, 2025 •

edited

Loading

svc-apollo-docs commented Jan 3, 2025 •

edited

Loading

monkpow Jan 6, 2025 •

edited

Loading