Onboarding experience

[o0Ignition0o]

This issue will cover the various things I would like to work on before reveal in order to facilitate the newcomers onboarding experience on the router.

This includes:

• routing (pun intended) newcomers through this repo to successfully set up and run the router (possibly with the supergraph demo, or a variant of it).

• Allowing users to run the router and the subservices locally, possibly using docker and docker-compose.

• give quickstart information to new users.

• Set new contributors up for success.

I'm making a lot of assumptions, and trying to map these with things we can do to help, please comment on this issue so we can update assumptions, pain points, and plans to fix accordingly.

User shortest path to success:

Users will probably come to the repo, git clone it, and then cargo run.
Some may read the README.md file before (or after), and possibly look for a QUICKSTART.md file, but not much more.

Pain point

The router needs to be passed a -p configuration. This means the first cargo run will lead to an error.

Solution

We want to provide hints in the README.md, as well as in an eventual QUICKSTART.md, and one more hint when running cargo run.

This is the current message we receive when running cargo run:

     Running `target/debug/router`
Nov 02 16:19:43.597 ERROR apollo_router: Configuration file at path '/Users/ignition/Library/Application Support/com.Apollo.Federation/configuration.yaml' does not exist.
Nov 02 16:19:43.598 ERROR apollo_router: Schema file at path '/Users/ignition/Library/Application Support/com.Apollo.Federation/supergraph.graphql' does not exist.
Nov 02 16:19:43.598  INFO router: Starting Apollo Router
Nov 02 16:19:43.599  INFO router: Stopped with error
Nov 02 16:19:43.599 ERROR router: Configuration was not supplied.
Error: Configuration was not supplied.

We know for sure no configuration file path has been provided, which means we can hint the users to provide one, and that if they want to play with the router, there's a supergraph demo example available near by:

expected message could look like:

⚠️ Missing configuration: the router looked for a configuration, but couldn't find any.
Please provide a configuration by passing `-p path/to/a/configuration/folder` or both `--config path/to/configuration.yaml` and `--schema path/to/valid/supergraph/schema.graphql`.
💡 If you are running the router for the first time and would like to run a demonstration, you can pass `-p ./examples/supergraphdemo`

we could also add a quickstart folder with a simple example, our own subservices.

---

README / QUICKSTART:

Provide instructions on how to docker-compose up the subservices, and run the router with the supergraphdemo example.

cc @abernix for anything you deem relevant for this to happen, and any other onboarding related issues you might think of

All of this can also be reflected in the docs.

[cecton]

routing (pun intended) newcomers through this repo to successfully set up and run the router (possibly with the supergraph demo, or a variant of it)

This is done already in DEVELOPMENT.md. Can you provide more points on what you would like to add/modify.

Provide instructions on how to docker-compose up the subservices, and run the router with the supergraphdemo example.

This is the exact same point than the "routing" so I'm putting this here. But let me know if you had something else in mind. You can create another discussion thread for it.

[Geal]

I thought this was more about onboarding users of the router, than developers?

[cecton]

Ok I misunderstood that

[cecton]

Allowing users to run the router and the subservices locally, possibly using docker and docker-compose

This is already possible. The user can run the subservices locally using docker with docker-compose or they can run the federation-demo directly without docker.

Can you provide more points on what you would like to add/modify.

[cecton]

give quickstart information to new users.

This is done already in DEVELOPMENT.md. Can you provide more points on what you would like to add/modify.

[cecton]

Set new contributors up for success.

This sounds more like a philosophical point. Can you give more details on what you have in mind and how concretely it translates?

[cecton]

Pain point: the router needs to be passed a -p configuration. This means the first cargo run will lead to an error

I agree that this is not ideal. One other problem related to this is that there is nowhere in the DEVELOPMENT.md that explains how to run it. You have to figure that out by yourself.

Solutions

1. Add the information to the DEVELOPMENT.md

2. Add a warning to the router binary on startup (your proposal):

   ⚠️ Missing configuration: the router looked for a configuration, but couldn't find any.
   Please provide a configuration by passing -p path/to/a/configuration/folder or both --config path/to/configuration.yaml and --schema path/to/valid/supergraph/schema.graphql.
   💡 If you are running the router for the first time and would like to run a demonstration, you can pass -p ./examples/supergraphdemo

3. Rust allows "example" binaries to be ran. This is a common pattern for the Rust programming language. Doc here: https://doc.rust-lang.org/cargo/reference/cargo-targets.html#examples

Examples for solution 3

Here is a directory structure:

.
├── Cargo.toml
└── examples
   └── router-dev.rs

It is expected that Rust developer knows how to run the router-dev.rs example. The command is cargo run --example router-dev.

Since router is also designed as a library. We can make this router-dev.rs and we can make it assume the location of the configuration files.

It is also possible to have complete "example crate" like this:

.
├── examples
│  └── router-dev
│     ├── src
│     │  └── main.rs
│     ├── Cargo.toml
│     ├── configuration.yaml
│     └── supergraph.graphql
└── Cargo.toml

In this example you can use the same command to run the example: cargo run --example router-dev.

Even though the Rust developer is expected to know how to run an example. It is nice to leave a quick note in the DEVELOPMENT.md on how to run it by giving the actual command.

[Geal]

the -p argument was removed recently: ddc883e
it was too confusing

[Geal]

also with b321fa0 we can now make the configuration file optional: starting the router with only the supergraph will start it it on 127.0.0.1:4000, without CORS override, without backend service address override, without telemetry

[cecton]

I'm fine with this proposal.

[cecton]

Users will probably come to the repo, git clone it, and then cargo run.
Some may read the README.md file before (or after), and possibly look for a QUICKSTART.md file, but not much more.

I understand here that you want the example and the dev environment to run as simply as possible. Preferably with a oneline command like cargo run. Please let me know if I'm not hearing you correctly.

There is a "complicated question" here because the router does not actually do anything on its own. It's not like the deps.rs server that you can run and it works without the need of external services. Here you need:

1. at least the subgraphs to be running
2. the gateway to be running to run the integration test

Current situation

It is important to note that in the current setup of the router repository there is only one command to run the subgraphs and the gateway: docker compose up -d. Using docker is quite a common pattern and people will know how to do it.

Some people don't like the idea to run containers and will prefer to run things natively without container. This is okay and it is already explained in the Quickstart section of the DEVELOPMENT.md.

This submodule initialization is not explained in the quickstart when using docker. This should be improved.

My personal view

I'm personally not one in favor of a one-command-does-all in this situation because I believe the user must make a conscious choice to run the subgraphs, gateway and the router. Otherwise they have no idea what is running on their machine. That being said, I'm not again an xtask that would run the subgraphs and gateway in one shot. Nevertheless, even if it's not yet an xtask, the docker compose up -d command is already this "one command that runs the background things".

[cecton]

Outdated information in the DEVELOPMENT.md that should be fixed:

• https://github.com/apollographql/router/blob/main/DEVELOPMENT.md#crates
  The crates are currently apollo-router and apollo-router-core
• https://github.com/apollographql/router/blob/main/DEVELOPMENT.md#strict-linting
  I don't think this script is still used. We should probably update this to cargo xtask lint

[cecton]

We should probably add in DEVELOPMENT.md that the complete CI tests can be ran using the command cargo xtask test --no-demo and the lint with cargo xtask lint.

The --no-demo should probably be the default instead of being an opt-in options because usually you don't want to run that locally (you're supposed to already run the subgraphs and gateway by other means). This feature was done for simplifying the CI yaml. It worked great on GitHub Actions but not so great on CircleCI (it doesn't work for the Windows build for some reason).

Some people prefer to have Git hooks for running those tests and lint locally instead of waiting for CI. I think we should provide those. Git hooks are always opt-in so someone who don't like them can disable them locally easily.