docs: router naming conventions (#5400)

Co-authored-by: Maria Elisabeth Schreiber <[email protected]> Co-authored-by: Jesse Rosenberger <[email protected]> Co-authored-by: Chandrika Srinivasan <[email protected]>
apollographql · Jul 24, 2024 · b9936cc · b9936cc
1 parent dff748f
commit b9936cc
Show file tree

Hide file tree

Showing 71 changed files with 1,942 additions and 1,920 deletions.
diff --git a/.changesets/docs_eh_docs_router_renaming_conventions.md b/.changesets/docs_eh_docs_router_renaming_conventions.md
@@ -0,0 +1,8 @@
+### Update router naming conventions ([PR #5400](https://github.com/apollographql/router/pull/5400))
+
+Renames our router product to distinguish between our non-commercial and commercial offerings. Instead of referring to the **Apollo Router**, we now refer to the following:
+- **Apollo Router Core** is Apollo’s free-and-open (ELv2 licensed) implementation of a routing runtime for supergraphs. 
+- **GraphOS Router** is based on the Apollo Router Core and fully integrated with GraphOS. GraphOS Routers provide access to GraphOS’s commercial runtime features.
+
+
+By [@shorgi](https://github.com/shorgi) in https://github.com/apollographql/router/pull/5400
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,10 +1,10 @@
 <img src="https://raw.githubusercontent.com/apollographql/space-kit/main/src/illustrations/svgs/astronaut1.svg" width="100%" height="144">
 
-# Contributing to Apollo Router
+# Contributing to Apollo Router Core
 
-## Before you contribute!
+## Before you contribute
 
-> The Apollo Router is a project by [Apollo GraphQL] and is not currently ready for
+> The Apollo Router Core is a project by [Apollo GraphQL] and is not currently ready for
 > external feature contributors, though some documentation contributions may be
 > accepted. We will try to publish a roadmap as soon as possible.
 
@@ -14,10 +14,10 @@ That will allow us to figure out a way to solve the issue together, and possibly
 
 ## Setting up the project
 
-The Apollo Router is written in [Rust]. In order to contribute, you'll need to have Rust installed. To install Rust,
+The Apollo Router Core is written in [Rust]. In order to contribute, you'll need to have Rust installed. To install Rust,
 visit [https://www.rust-lang.org/tools/install].
 
-Rust has a build tool and package manager called [`cargo`] that you'll use to interact with the Apollo Router's code.
+Rust has a build tool and package manager called [`cargo`] that you'll use to interact with the router's code.
 
 To build the CLI:
 
@@ -29,7 +29,7 @@ To run the CLI:
 
 ```bash
 cargo run -- <args>
-# e.g. 'cargo run -- --help' will run the Apollo Router's help command
+# e.g. 'cargo run -- --help' will run the router's help command
 ```
 
 Refer to [the README file](README.md) or run `cargo run --help` for more information.
@@ -41,7 +41,7 @@ Refer to [the README file](README.md) or run `cargo run --help` for more informa
 
 ## Project Structure
 
-- `crates/apollo-router`: the web `Apollo Router` sources. This includes everything required to expose Apollo Router's functionality as a web server, such as serialization / deserialization, configuration management, web server set up, logging configuration etc. As well as everything required to handle graphql queries:
+- `crates/apollo-router`: the web `Apollo Router` sources. This includes everything required to expose Apollo Router Core's functionality as a web server, such as serialization / deserialization, configuration management, web server set up, logging configuration etc. As well as everything required to handle graphql queries:
 
   - query plan building
   - query plan execution
@@ -55,15 +55,15 @@ Some of the functionalities rely on the current Javascript / TypeScript implemen
 
 ## Documentation
 
-Documentation for using and contributing to the Apollo Router is built using Gatsby
+Documentation for using and contributing to the Apollo Router Core is built using Gatsby
 and [Apollo's Docs Theme for Gatsby](https://github.com/apollographql/gatsby-theme-apollo/tree/master/packages/gatsby-theme-apollo-docs)
 .
 
 To contribute to these docs, you can add or edit the markdown & MDX files in the `docs/source` directory.
 
-To build and run the documentation site locally, you'll also need a clone of 
+To build and run the documentation site locally, you'll also need a clone of
 the [apollographql/docs](https://github.com/apollographql/docs/) repository
-and run `npm run start:router` from there, after following 
+and run `npm run start:router` from there, after following
 [installation instructions](https://github.com/apollographql/docs/#developing-locally).
 
 This will start up a development server with live reload enabled. You can see the docs by
@@ -87,7 +87,7 @@ XTASKs:
 
 - **Tests**: The CI will run `cargo xtask test` which will test each relevant permutation of the available features and run the demo subgraphs.
 - **Lints**: The CI will check for lints and clippy compliance.
-- **Checks**: The CI will run cargo-deny to make sure the Apollo Router doesn't suffer an existing CVE, and that each dependency used by the Apollo Router is compatible with our license.
+- **Checks**: The CI will run cargo-deny to make sure the router doesn't suffer an existing CVE, and that each dependency used by the router is compatible with our license.
 
 After you have opened your PR and all of the status checks are passing, please assign it to one of the maintainers (found in the bottom of [the README](./README.md#contributing) who will review it and give feedback.
 

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -1,26 +1,26 @@
 # Development
 
-The **Apollo Router** is a configurable, high-performance **graph router** for a [federated graph](https://www.apollographql.com/docs/federation/):
+The **Apollo Router Core** is a configurable, high-performance **graph router** for a [federated graph](https://www.apollographql.com/docs/federation/):
 
 ## Crates
 
- *   `configuration` - Config model and loading.
- *   `query planner` - Query plan model and a caching wrapper for calling out to the nodejs query planner.
- *   `execution` - Converts a query plan to a stream.
- *   `server` - Handles requests,
+* `configuration` - Config model and loading.
+* `query planner` - Query plan model and a caching wrapper for calling out to the nodejs query planner.
+* `execution` - Converts a query plan to a stream.
+* `server` - Handles requests,
      obtains a query plan from the query planner,
      obtains an execution pipeline,
      returns the results
 
 ## Binaries
 
- *   `router` - Starts a server.
+* `router` - Starts a server.
 
 ## Development
 
-You will need a recent version of rust (`1.72` works well as of writing). 
+You will need a recent version of rust (`1.72` works well as of writing).
 Installing rust [using rustup](https://www.rust-lang.org/tools/install) is
-the recommended way to do it as it will install rustup, rustfmt and other 
+the recommended way to do it as it will install rustup, rustfmt and other
 goodies that are not always included by default in other rust distribution channels:
 
 ```
@@ -39,9 +39,9 @@ git config --local core.hooksPath .githooks/
 
 Use `cargo build --all-targets` to build the project.
 
-Some tests use external services such as Jaeger and Redis. 
+Some tests use external services such as Jaeger and Redis.
 
-To start these services: 
+To start these services:
 
 ```
 docker-compose up -d
@@ -51,16 +51,16 @@ docker-compose up -d
 have issues and you want to see the logs or if you want to run the service
 in foreground.
 
-### Run Apollo Router against the docker-compose or Node.js setup
+### Run against the docker-compose or Node.js setup
 
-Once the subgraphs are up and running, run Apollo Router with this command:
+Once the subgraphs are up and running, run the router with this command:
 
 ```shell
 cargo run --release -- -s ./examples/graphql/local.graphql -c examples/telemetry/jaeger.router.yaml
 ```
 
-Go to https://studio.apollographql.com/sandbox/explorer to make queries and
-http://localhost:16686/ to reach Jaeger.
+Go to <https://studio.apollographql.com/sandbox/explorer> to make queries and
+<http://localhost:16686/> to reach Jaeger.
 
 ### Strict linting and license compliance
 
@@ -73,11 +73,13 @@ and check for license compliance.
 Use `cargo xtask all` to run all of the checks the CI will run.
 
 The CI checks require `cargo-deny` and `cargo-about` which can both be installed by running:
-- `cargo install cargo-deny`
-- `cargo install cargo-about`
+
+* `cargo install cargo-deny`
+* `cargo install cargo-about`
 
 Updating the snapshots used during testing requires installing `cargo-insta`:
-- `cargo install cargo-insta`
+
+* `cargo install cargo-insta`
 
 They also need you to have the federation-demo project up and running,
 as explained in the Getting started section above.
@@ -86,7 +88,6 @@ as explained in the Getting started section above.
 
 If you are adding a new feature or modifying an existing feature then consult the [yaml design guidance](dev-docs/yaml-design-guidance.md) page.
 
-
 ### Investigating memory usage
 
 There are two features: `dhat-heap` and `dhat-ad-hoc` which may be enabled for investigating memory issues
@@ -95,11 +96,13 @@ with the router. You may enable either or both, depending on the kind of problem
 You have to build the router with your choice of feature flags and you must use the `release-dhat` profile.
 
 e.g.: heap and ad-hoc allocation tracing
+
 ```shell
 # e.g. heap and ad-hoc allocation tracing: cargo build --profile release-dhat --features dhat-heap,dhat-ad-hoc
 ```
 
 e.g.: heap allocation tracing
+
 ```shell
 cargo build --profile release-dhat --features dhat-heap 
 ```
@@ -113,7 +116,7 @@ For more details on interpreting these files and running tests, see the [dhat-rs
 
 ### Troubleshoot
 
-+ If you have an issue with rust-analyzer reporting an unresolved import about `derivative::Derivative` [check this solution](https://github.com/rust-analyzer/rust-analyzer/issues/7459#issuecomment-876796459) found in a rust-analyzer issue.
+* If you have an issue with rust-analyzer reporting an unresolved import about `derivative::Derivative` [check this solution](https://github.com/rust-analyzer/rust-analyzer/issues/7459#issuecomment-876796459) found in a rust-analyzer issue.
 
 ## Project maintainers
 

diff --git a/README.md b/README.md
@@ -2,25 +2,25 @@
 
 [![CircleCI](https://circleci.com/gh/apollographql/router/tree/main.svg?style=shield)](https://circleci.com/gh/apollographql/router/tree/main)
 
-# Apollo Router
+# Apollo Router Core
 
-The **Apollo Router** is a configurable, high-performance **graph router** written in Rust to run a [federated supergraph](https://www.apollographql.com/docs/federation/) that uses [Apollo Federation 2](https://www.apollographql.com/docs/federation/v2/federation-2/new-in-federation-2).
+The **Apollo Router Core** is a configurable, high-performance **graph router** written in Rust to run a [federated supergraph](https://www.apollographql.com/docs/federation/) that uses [Apollo Federation 2](https://www.apollographql.com/docs/federation/v2/federation-2/new-in-federation-2).
 
-Apollo Router is well-tested, regularly benchmarked, includes most major features of Apollo Gateway and is able to serve production-scale workloads. Please note that the (pre-1.0) version is not yet "semver stable" and we may still make breaking changes. Generally speaking, we expect most breaking changes to be on the plugin API and the configuration file format. We will clearly convey such changes in the release notes.
+Apollo Router Core is well-tested, regularly benchmarked, includes most major features of Apollo Gateway and is able to serve production-scale workloads.
 
 New releases and their release notes (along with notes about any breaking changes) can be found on the [Releases](https://github.com/apollographql/router/releases) page, and the latest release can always be found [on the latest page](https://github.com/apollographql/router/releases/latest). The `CHANGELOG.md` at the root of this repository also contains _unreleased_ changes in addition to the full history of changes.
 
 Currently, we're publishing new releases every 1-2 weeks.
 
 ## Getting started
 
-Follow the [quickstart tutorial](https://www.apollographql.com/docs/router/quickstart/) to get up and running with the Apollo Router.
+Follow the [quickstart tutorial](https://www.apollographql.com/docs/router/quickstart/) to get up and running with the router.
 
 See [the documentation](https://www.apollographql.com/docs/router) for more details.
 
 ## Usage
 
-Apollo Router requires [a supergraph file](https://www.apollographql.com/docs/rover/commands/supergraphs/) to be passed as the `--supergraph` argument and [an optional configuration file](https://www.apollographql.com/docs/router/configuration/overview/#yaml-config-file).
+Apollo Router Core requires [a supergraph file](https://www.apollographql.com/docs/rover/commands/supergraphs/) to be passed as the `--supergraph` argument and [an optional configuration file](https://www.apollographql.com/docs/router/configuration/overview/#yaml-config-file).
 to be supplied. These are either located in the current directory or explicitly
 specified via flag, either by an absolute path, or a path relative to the current
 directory.
@@ -63,7 +63,7 @@ Options:
 
 [Apollo](https://apollographql.com/) is building software and a graph platform to unify GraphQL across your apps and services. We help you ship faster with:
 
-* [Apollo Studio](https://www.apollographql.com/graphos) – A free, end-to-end platform for managing your GraphQL lifecycle. Track your GraphQL schemas in a hosted registry to create a source of truth for everything in your graph. Studio provides an IDE (Apollo Explorer) so you can explore data, collaborate on queries, observe usage, and safely make schema changes.
+* [Apollo GraphOS Studio](https://www.apollographql.com/graphos) – A free, end-to-end platform for managing your GraphQL lifecycle. Track your GraphQL schemas in a hosted registry to create a source of truth for everything in your graph. GraphOS Studio provides an IDE (Apollo Explorer) so you can explore data, collaborate on queries, observe usage, and safely make schema changes. GraphOS Router is a scalable runtime for supergraphs that's fully integrated with GraphOS Studio and based on the Apollo Router Core.
 * [Apollo Federation](https://www.apollographql.com/docs/federation/) – The industry-standard open architecture for building a distributed graph. Compose and manage your graphs using [Rover](https://www.apollographql.com/docs/rover) and then use Apollo Router to query plan and route requests across multiple subgraphs.
 * [Apollo Client](https://www.apollographql.com/docs/react/) – The most popular GraphQL client for the web. Apollo also builds and maintains [Apollo iOS](https://github.com/apollographql/apollo-ios) and [Apollo Android](https://github.com/apollographql/apollo-android).
 * [Apollo Server](https://www.apollographql.com/docs/apollo-server/) – A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments.
@@ -74,7 +74,7 @@ Check out the [Odyssey](https://odyssey.apollographql.com/) learning platform, t
 
 ## Design principles
 
-The development of the Apollo Router is driven by the following design principles that inform
+The development of the Apollo Router Core is driven by the following design principles that inform
 architecture decisions and implementation.
 
 **Correctness:** the router strives to be the most correct implementation of GraphQL and Federation, we care about testing and documenting everything implied by the specification, up to failure cases. The router’s behavior should follow the principle of least surprise for developers.
@@ -84,6 +84,7 @@ architecture decisions and implementation.
 **Safe experimentation:** the router will support all the future work around Federation, so it must allow new ideas and explorations without disturbing existing features. The project is still in movement, we cannot allow it to crystallize too early, while still following the principles of correctness and reliability.
 
 **Usability:** the router must be simple to operate. Prefer extensibility over configuration options, and ensure that the user has enough information to help themselves when things go wrong. For example:
+
 * Common environmental misconfiguration should be detected and surfaced to the user in the form of mitigation steps.
 * User supplied extensions should be observable and flagged when they cause performance issues. Tell the users how much time an extension is consuming per request and why.
 

diff --git a/apollo-router/README.md b/apollo-router/README.md
@@ -1,11 +1,11 @@
 [![Version](https://img.shields.io/crates/v/apollo-router.svg)](https://crates.io/crates/apollo-router)
 [![Docs.rs](https://docs.rs/apollo-router/badge.svg)](https://docs.rs/apollo-router)
 
-# Apollo Router
+# Apollo Router Core
 
 [<img alt="Apollo Router" src="https://raw.githubusercontent.com/apollographql/space-kit/main/src/illustrations/svgs/satellite1.svg" height="144">](https://www.apollographql.com/docs/router/)
 
-The **Apollo Router** is a configurable, high-performance **graph router** written in Rust to run a [federated supergraph](https://www.apollographql.com/docs/federation/) that uses [Apollo Federation 2](https://www.apollographql.com/docs/federation/v2/federation-2/new-in-federation-2). It is well-tested, regularly benchmarked, includes major features of Apollo Gateway and serves production-scale workloads.
+The **Apollo Router Core** is a configurable, high-performance **graph router** written in Rust to run a [federated supergraph](https://www.apollographql.com/docs/federation/) that uses [Apollo Federation 2](https://www.apollographql.com/docs/federation/v2/federation-2/new-in-federation-2). It is well-tested, regularly benchmarked, includes major features of Apollo Gateway and serves production-scale workloads.
 
 The latest release can always be found at the top of [the Releases page](https://github.com/apollographql/router/releases/) along with past releases and release notes.  We follow the [Semantic Versioning 2.0.0](https://semver.org/) specification when publishing new versions.  A [`CHANGELOG.md` is also included](https://github.com/apollographql/router/blob/main/CHANGELOG.md) in the Git repository with information about each release.
 
@@ -20,9 +20,9 @@ See [the documentation](https://www.apollographql.com/docs/router) for more deta
 - including additional customizations
 - from source, and more!
 
-## Using the Apollo Router as a library
+## Using the Apollo Router Core as a library
 
-Most Apollo Router features can be defined using our [YAML configuration](https://www.apollographql.com/docs/router/configuration/overview) and many customizations can be written with [Rhai scripts](https://www.apollographql.com/docs/router/customizations/rhai) which work on published binaries of the Router and do not require compilation.
+Most Apollo Router Core features can be defined using our [YAML configuration](https://www.apollographql.com/docs/router/configuration/overview) and many customizations can be written with [Rhai scripts](https://www.apollographql.com/docs/router/customizations/rhai) which work on published binaries of the router and do not require compilation.
 
 If you prefer to write customizations in Rust or need more advanced customizations, see our section on [native customizations](https://www.apollographql.com/docs/router/customizations/native) for information on how to use `apollo-router` as a Rust library.  We also publish Rust-specific documentation on our [`apollo-router` crate docs](https://docs.rs/crate/apollo-router).
 

diff --git a/docs/shared/elastic-notice.mdx b/docs/shared/elastic-notice.mdx
@@ -1,5 +1,5 @@
 <Note>
 
-The Apollo Router source code and all its distributions are made available under the [Elastic License v2.0 (ELv2) license](https://www.apollographql.com/docs/resources/elastic-license-v2-faq/#can-i-extend-or-modify-the-gateway-or-router-by-creating-plugins).
+The Apollo Router Core source code and all its distributions are made available under the [Elastic License v2.0 (ELv2) license](https://www.apollographql.com/docs/resources/elastic-license-v2-faq/#can-i-extend-or-modify-the-gateway-or-router-by-creating-plugins).
 
 </Note>
diff --git a/docs/shared/native-plugin-notice.mdx b/docs/shared/native-plugin-notice.mdx
@@ -1,4 +1,4 @@
-⚠️ **Apollo doesn't recommend creating native plugins for the Apollo Router**, for the following reasons:
+⚠️ Apollo doesn't recommend creating native plugins for the Apollo Router Core or GraphOS Router, for the following reasons:
 
 - Native plugins require familiarity with programming in Rust.
 - Native plugins require compiling a custom router binary from source, which can introduce unexpected behavior in your router that's difficult to diagnose and support.