feat: updates harmonizer to v0.30.0 (#832)

* feat: updates harmonizer to v0.30.0

* docs: adds gateway compatibility section to compose docs

* chore: address trevor's review comments

* docs: rewrite gateway compat content

Co-authored-by: Jesse Rosenberger <[email protected]>

* chore: add --branch to xtask integration-test

* chore: add --org to xtask integration-test

* docs: clarify @tag repeatable requirements

* chore: updates harmonizer to v0.33.0

* docs: removes unnecessary breaking change

* docs: polish gateway compat

Co-authored-by: Jesse Rosenberger <[email protected]>

Author: EverlastingBugstopper

Cargo.lock

@@ -51,7 +51,7 @@ console = "0.14"
 crossterm = "0.21"
 git-url-parse = "0.3"
 git2 = { version = "0.13", default-features = false, features = ["vendored-openssl"] }
-harmonizer = { version = "0.27.0", optional = true }
+harmonizer = { version = "0.33.0", optional = true }
 heck = "0.3"
 lazycell = "1"
 opener = "0.5"

Cargo.toml

@@ -33,11 +33,11 @@ The `supergraph compose` command's `--config` option expects the path to a YAML
 subgraphs:
   films:
     routing_url: https://films.example.com
-    schema: 
+    schema:
       file: ./films.graphql
   people:
     routing_url: https://people.example.com
-    schema: 
+    schema:
       file: ./people.graphql
 ```
 
@@ -49,17 +49,17 @@ It's also possible to pull subgraphs from various sources and specify them in th
 subgraphs:
   films:
     routing_url: https://films.example.com
-    schema: 
+    schema:
       file: ./films.graphql
   people:
     routing_url: https://example.com/people
-    schema: 
+    schema:
       subgraph_url: https://example.com/people
   actors:
     routing_url: https://localhost:4005
-    schema: 
-      graphref: mygraph@current 
-      subgraph: actors 
+    schema:
+      graphref: mygraph@current
+      subgraph: actors
 ```
 
 ### Output format
@@ -74,3 +74,16 @@ rover supergraph compose --config ./supergraph.yaml > prod-schema.graphql
 ```
 
 > For more on passing values via `stdout`, see [Using `stdout`](./conventions#using-stdout).
+
+#### Gateway compatibility
+
+The `rover supergraph compose` command produces a supergraph schema by using composition functions from the [`@apollo/federation`](https://www.apollographql.com/docs/federation/api/apollo-federation/) package. Because that library is still in pre-1.0 releases (as are Rover and Apollo Gateway), some updates to Rover might result in a supergraph schema with new functionality. In turn, this might require corresponding updates to your gateway.
+
+Apollo Gateway fails to start up if it's provided with a supergraph schema that it doesn't support. To ensure compatibility, we recommend that you test launching your gateway in a CI pipeline with the supergraph schema it will ultimately use in production.
+
+We aim to reduce the frequency at which these paired updates are necessary by making supergraph additions backwards compatible. We will note changes that require corresponding Apollo Gateway updates clearly in the Rover _Release Notes_, and we'll also update the following compatibility table.
+
+|Rover version|Gateway version|
+|---|---|
+|<= v0.2.x|<= v0.38.x|
+|>= v0.3.x|>= v0.39.x|

docs/source/supergraphs.md

@@ -9,6 +9,14 @@ pub struct IntegrationTest {
     // The target to build Rover for
     #[structopt(long = "target", env = "XTASK_TARGET", default_value, possible_values = &[TARGET_GNU_LINUX])]
     pub(crate) target: Target,
+
+    // The supergraph-demo branch to check out
+    #[structopt(long = "branch", default_value = "main")]
+    pub(crate) branch: String,
+
+    // The supergraph-demo org to clone
+    #[structopt(long = "org", default_value = "apollographql")]
+    pub(crate) org: String,
 }
 
 impl IntegrationTest {
@@ -22,7 +30,7 @@ impl IntegrationTest {
                 MakeRunner::new(verbose, cargo_runner.get_bin_path(&self.target, release)?)?;
             cargo_runner.build(&self.target, release, None)?;
 
-            let repo_path = git_runner.clone_supergraph_demo()?;
+            let repo_path = git_runner.clone_supergraph_demo(&self.org, &self.branch)?;
             make_runner.test_supergraph_demo(&repo_path)?;
         } else {
             crate::info!("skipping integration tests for --target {}", &self.target);

xtask/src/commands/integration_test.rs

@@ -19,6 +19,8 @@ impl Test {
         unit_test_runner.run(verbose)?;
         let integration_test_runner = IntegrationTest {
             target: self.target.clone(),
+            branch: Default::default(),
+            org: Default::default(),
         };
         integration_test_runner.run(verbose)?;
         Ok(())

xtask/src/commands/test.rs

@@ -28,11 +28,14 @@ impl GitRunner {
         })
     }
 
-    pub(crate) fn clone_supergraph_demo(&self) -> Result<Utf8PathBuf> {
+    pub(crate) fn clone_supergraph_demo(&self, org: &str, branch: &str) -> Result<Utf8PathBuf> {
         let repo_name = "supergraph-demo";
-        let repo_url = format!("https://github.com/apollographql/{}", repo_name);
-        self.runner
-            .exec(&["clone", &repo_url], &self.temp_dir_path, None)?;
+        let repo_url = format!("https://github.com/{}/{}", org, repo_name);
+        self.runner.exec(
+            &["clone", &repo_url, "--branch", branch],
+            &self.temp_dir_path,
+            None,
+        )?;
 
         let repo_path = self.temp_dir_path.join(repo_name);
         Ok(repo_path)