Merge branch 'dev' into njm/P-416/pq-reporting

Author: bonnici

RELEASE_CHECKLIST.md

@@ -70,8 +70,8 @@ This project uses [Semantic Versioning 2.0.0](https://semver.org/).  When releas
 
 Creating a release PR is the first step of starting a release, whether there will be pre-releases or not.  About a release PR:
 
-* A release PR is based on a release branch and a release branch gathers all the commits for a release.
-* The release PR merges into `main` at the time that the release becomes official.
+* A release PR is based on a mainline release line (e.g., `dev`, or `1.x`) and a release branch gathers all the commits for a release.
+* The release PR merges into the mainline at the time that the release becomes official.
 * A release can be started from any branch or commit, but it is almost always started from `dev` as that is the main development trunk of the Router.
 * The release PR is in a draft mode until after the preparation PR has been merged into it.
 
@@ -111,24 +111,30 @@ Start following the steps below to start a release PR.  The process is **not ful
    git checkout -b "${APOLLO_ROUTER_RELEASE_VERSION}"
    ```
 
-7. Push this new branch to the appropriate remote.  We will open a PR for it **later**, but this will be the **base** for the PR created in the next step).  (And `--set-upstream` will of course track this locally.  This is commonly abbreviated as `-u`.)
+7. Add an empty commit to the branch.  This isn't always necessary, but it allows the staging PR to be opened when there is no other difference to the base-branch (e.g., `dev`) which prevents the PR from getting opened, even in draft mode.
+
+   ```
+   git commit --allow-empty -m "Start v${APOLLO_ROUTER_RELEASE_VERSION} PR"
+   ```
+
+8. Push this new branch to the appropriate remote.  We will open a PR for it **later**, but this will be the **base** for the PR created in the next step).  (And `--set-upstream` will of course track this locally.  This is commonly abbreviated as `-u`.)
 
    ```
    git push --set-upstream "${APOLLO_ROUTER_RELEASE_GIT_ORIGIN}" "${APOLLO_ROUTER_RELEASE_VERSION}"
    ```
 
-8. Now, open a draft PR with a small boilerplate header from the branch which was just pushed:
+9. Now, open a draft PR with a small boilerplate header from the branch which was just pushed:
 
    ```
-   cat <<EOM | gh --repo "${APOLLO_ROUTER_RELEASE_GITHUB_REPO}" pr create --draft --label release -B "main" --title "release: v${APOLLO_ROUTER_RELEASE_VERSION}" --body-file -
+   cat <<EOM | gh --repo "${APOLLO_ROUTER_RELEASE_GITHUB_REPO}" pr create --draft --label release -B "dev" --title "release: v${APOLLO_ROUTER_RELEASE_VERSION}" --body-file -
    > **Note**
-   > **This particular PR must be true-merged to \`main\`.**
+   > **This particular PR must be true-merged to \`dev\`.**
 
-   * This PR is only ready to review when it is marked as "Ready for Review".  It represents the merge to the \`main\` branch of an upcoming release (version number in the title).
+   * This PR is only ready to review when it is marked as "Ready for Review".  It represents the merge to the \`dev\` branch of an upcoming release (version number in the title).
    * It will act as a staging branch until we are ready to finalize the release.
    * We may cut any number of alpha and release candidate (RC) versions off this branch prior to formalizing it.
    * This PR is **primarily a merge commit**, so reviewing every individual commit shown below is **not necessary** since those have been reviewed in their own PR.  However, things important to review on this PR **once it's marked "Ready for Review"**:
-       - Does this PR target the right branch? (usually, \`main\`)
+       - Does this PR target the right branch? (usually, \`dev\`)
        - Are the appropriate **version bumps** and **release note edits** in the end of the commit list (or within the last few commits).  In other words, "Did the 'release prep' PR actually land on this branch?"
        - If those things look good, this PR is good to merge!
    EOM
@@ -246,7 +252,7 @@ Start following the steps below to start a release PR.  The process is **not ful
      - Run our compliance checks and update the `licenses.html` file as appropriate.
      - Ensure we're not using any incompatible licenses in the release.
 
-7. **MANUALLY CHECK AND UPDATE** the `federation-version-support.mdx` to make sure it shows the version of Federation which is included in the `router-bridge` that ships with this version of Router.  This can be obtained by looking at the version of `router-bridge` in `apollo-router/Cargo.toml` and taking the number after the `+` (e.g., `router-bridge@0.2.0+v2.4.3` means Federation v2.4.3).
+7. **MANUALLY CHECK AND UPDATE** the `federation-version-support.mdx` to make sure it shows the version of Federation which is supported by the Routter.
 
 11. Now, review and stage he changes produced by the previous step.  This is most safely done using the `--patch` (or `-p`) flag to `git add` (`-u` ignores untracked files).
 

apollo-router/src/plugins/telemetry/proto/reports.proto

@@ -581,9 +581,9 @@ message ContextualizedStats {
 }
 
 message QueryMetadata {
-  // The operation name. For now this is a required field if QueryMetadata is present.
+  // The operation name. For operations with a PQ ID as the stats report key, either name or signature must be present in the metadata.
   string name = 1;
-  // the operation signature. For now this is a required field if QueryMetadata is present.
+  // the operation signature. For operations with a PQ ID as the stats report key, either name or signature must be present in the metadata.
   string signature = 2;
   // (Optional) Persisted query ID that was used to request this operation.
   string pq_id = 3;

docs/source/routing/configuration.mdx

@@ -1208,15 +1208,17 @@ supergraph:
 When the Router schema or configuration updates all connections must be closed for resources to be freed.
 To ensure that long-lived connections do not hang on to resources, a maximum graceful shutdown timeout can be configured.
 
-```yaml
-connection_shutdown_timeout: 60s
+```yaml title="router.yaml"
+supergraph:
+  connection_shutdown_timeout: 60s
 ```
 
 The default value is 60 seconds.
 
 Note that if `early_cancel` is `false` (default), then requests in progress will still hold onto pipeline resources.
 Traffic shaping request timeouts should be used to prevent long-running requests.
-```
+
+```yaml title="router.yaml"
 traffic_shaping:
   router:
     timeout: 60s