New release process (part 7) (#2998)

<!--
Open the PR up as a draft until you feel it is ready for a proper
review.

Do not make PR:s from your own `main` branch, as that makes it difficult
for reviewers to add their own fixes.

Add any improvements to the branch as new commits to make it easier for
reviewers to follow the progress. All commits will be squashed to a
single commit once the PR is merged into `main`.

Make sure you mention any issues that this PR closes in the description,
as well as any other related issues.

To get an auto-generated PR description you can put "copilot:summary" or
"copilot:walkthrough" anywhere.
-->

### What

- Fixes everything after the `version` step of the prerelease workflow
not being executed on top of the version bump commit.
- Adds some documentation for the `deploy-vercel` action.

### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested [demo.rerun.io](https://demo.rerun.io/pr/{{
pr.number }}) (if applicable)

- [PR Build Summary](https://build.rerun.io/pr/{{ pr.number }})
- [Docs preview](https://rerun.io/preview/{{
"pr:%s"|format(pr.branch)|encode_uri_component }}/docs)
- [Examples preview](https://rerun.io/preview/{{
"pr:%s"|format(pr.branch)|encode_uri_component }}/examples)

.github/actions/deploy-vercel/action.yml

@@ -4,6 +4,7 @@
 
 name: "Deploy rerun.io"
 
+# Changing these inputs also requires changing their usage in `index.mjs`
 inputs:
   vercel_token:
     description: "Vercel access token"

.github/actions/deploy-vercel/index.mjs

@@ -1,8 +1,9 @@
 // @ts-check
 
-import { Client } from "./client.mjs";
+import { Client } from "./vercel.mjs";
 import { assert, find, get, getRequiredInput } from "./util.mjs";
 
+// These inputs are defined in `action.yml`, and should be kept in sync
 const token = getRequiredInput("vercel_token");
 const teamName = getRequiredInput("vercel_team_name");
 const projectName = getRequiredInput("vercel_project_name");

.github/actions/deploy-vercel/util.mjs

@@ -1,6 +1,8 @@
 // @ts-check
 
 /**
+ * Return a GitHub Actions input, returning `null` if it was not set.
+ *
  * @param {string} name
  * @returns {string | null}
  */
@@ -10,6 +12,8 @@ export function getInput(name) {
 }
 
 /**
+ * Return a GitHub Actions input, throwing an error if it was not set.
+ *
  * @param {string} name
  * @returns {string}
  */
@@ -22,6 +26,8 @@ export function getRequiredInput(name) {
 }
 
 /**
+ * Assert that `value` is truthy, throwing an error if it is not.
+ *
  * @param {any} value
  * @param {string} [message]
  * @returns {asserts value}
@@ -33,18 +39,22 @@ export function assert(value, message) {
 }
 
 /**
+ * Returns a function that attempts to find an object with
+ * `key` set to `value` in an array of objects with `key` properties.
  *
  * @template {string} Key
  * @template {{ [p in Key]: string }} T
  * @param {Key} key
- * @param {string} name
+ * @param {string} value
  * @returns {(a: T[]) => T|null}
  */
-export function find(key, name) {
-  return (a) => a.find((v) => v[key] === name) ?? null;
+export function find(key, value) {
+  return (a) => a.find((v) => v[key] === value) ?? null;
 }
 
 /**
+ * Returns a function that attempts to retrieve the value at `index` from an array.
+ *
  * @template T
  * @param {number} index
  * @returns {(a: T[]) => T|null}

.github/actions/deploy-vercel/client.mjs → .github/actions/deploy-vercel/vercel.mjs

@@ -14,12 +14,18 @@
  * @typedef {"encrypted" | "secret"} EnvType
  */
 
+/**
+ * Vercel API Client
+ */
 export class Client {
   constructor(/** @type {string} */ token) {
     this.token = token;
   }
 
   /**
+   * Helper function to generate the URL for a given `endpoint`
+   * with query `params`.
+   *
    * @param {string} endpoint
    * @param {Params} [params]
    * @returns {URL}
@@ -31,8 +37,10 @@ export class Client {
   }
 
   /**
+   * HTTP GET an `endpoint` with query `params` and `headers`.
+   *
    * @template T
-   * @param {string} endpoint
+   * @param {string} endpoint - not the full URL, just the path, e.g. `v9/projects`
    * @param {Params} [params]
    * @param {Headers} [headers]
    * @returns {Promise<T>}
@@ -47,9 +55,11 @@ export class Client {
   }
 
   /**
+   * HTTP POST a `body` to an `endpoint` with query `params` and `headers`.
+   *
    * @template T
-   * @param {string} endpoint
-   * @param {Body} body
+   * @param {string} endpoint - not the full URL, just the path, e.g. `v9/projects`
+   * @param {Body} body - will be JSON encoded
    * @param {Params} [params]
    * @param {Headers} [headers]
    * @returns {Promise<T>}
@@ -67,9 +77,11 @@ export class Client {
   }
 
   /**
+   * HTTP PATCH a `body` to an `endpoint` with query `params` and `headers`.
+   *
    * @template T
-   * @param {string} endpoint
-   * @param {Body} body
+   * @param {string} endpoint - not the full URL, just the path, e.g. `v9/projects`
+   * @param {Body} body - will be JSON encoded
    * @param {Params} [params]
    * @param {Headers} [headers]
    * @returns {Promise<T>}
@@ -87,13 +99,18 @@ export class Client {
   }
 
   /**
+   * Return all available teams for the user authorized by this client's token.
+   *
    * @returns {Promise<Team[]>}
    */
   async teams() {
     return await this.get("v2/teams").then((r) => r.teams);
   }
 
   /**
+   * Return all available projects under a given team (`teamId`)
+   * for the user authorized by this client's token.
+   *
    * @param {string} teamId
    * @returns {Promise<Project[]>}
    */
@@ -102,6 +119,14 @@ export class Client {
   }
 
   /**
+   * Return deployments under a given team (`teamId`) and project (`projectId`).
+   *
+   * The endpoint used is a paginated one, but this call does not support pagination,
+   * and only returns the first 20 results.
+   *
+   * The results are sorted by their created date, so the latest deployment
+   * for the given `target` is at index `0`.
+   *
    * @param {string} teamId
    * @param {string} projectId
    * @param {"production" | "preview" | "development"} target
@@ -114,6 +139,8 @@ export class Client {
   }
 
   /**
+   * Return environment variables available to a project (`projectId`) under a team (`teamId`).
+   *
    * @param {string} teamId
    * @param {string} projectId
    * @returns {Promise<Env[]>}
@@ -123,6 +150,9 @@ export class Client {
   }
 
   /**
+   * Get the decrypted version of an environment variable (`envId`)
+   * available to a project (`projectId`) under a team (`teamId`).
+   *
    * @param {string} teamId
    * @param {string} projectId
    * @param {string} envId
@@ -133,6 +163,9 @@ export class Client {
   }
 
   /**
+   * Set an environment variable (`envId`), making it available to a project `projectId`
+   * under a team (`teamId`).
+   *
    * @param {string} teamId
    * @param {string} projectId
    * @param {string} envId
@@ -153,6 +186,11 @@ export class Client {
   }
 
   /**
+   * Trigger a redeploy of an existing deployment (`deploymentId`)
+   * of a project (`name`) under a specific team (`teamId`).
+   *
+   * The resulting deployment will be set as the current production deployment.
+   *
    * @param {string} teamId
    * @param {string} deploymentId
    * @param {string} name

.github/workflows/release.yml

@@ -40,6 +40,7 @@ jobs:
       previous: ${{ steps.versioning.outputs.previous }}
       current: ${{ steps.versioning.outputs.current }}
       final: ${{ steps.versioning.outputs.final }}
+      release-commit: ${{ steps.create-pull-request.outputs.pull-request-head-sha }}
 
     steps:
       - name: Checkout repository
@@ -87,6 +88,7 @@ jobs:
           echo "final=$final"       >> "$GITHUB_OUTPUT"
 
       - name: Create pull request
+        id: create-pull-request
         uses: peter-evans/[email protected]
         if: steps.versioning.outputs.previous != steps.versioning.outputs.current
         with:
@@ -159,7 +161,7 @@ jobs:
       PY_DOCS_VERSION_NAME: ${{ inputs.release-type == 'prerelease' && 'prerelease' || needs.version.outputs.final }}
       RS_DOCS_VERSION_NAME: ${{ inputs.release-type == 'prerelease' && 'prerelease' || 'head' }}
       UPDATE_LATEST: ${{ inputs.release-type == 'release' }}
-      RELEASE_COMMIT: ${{ github.sha }}
+      RELEASE_COMMIT: ${{ needs.version.outputs.release-commit }}
     secrets: inherit
 
   publish-crates:
@@ -168,6 +170,7 @@ jobs:
     uses: ./.github/workflows/reusable_release_crates.yml
     with:
       CONCURRENCY: ${{ github.ref_name }}
+      RELEASE_COMMIT: ${{ needs.version.outputs.release-commit }}
     secrets: inherit
 
   build-and-publish-wheels:
@@ -179,6 +182,7 @@ jobs:
       concurrency: ${{ github.ref_name }}
       linux-wheel-name: linux-wheel
       linux-rrd-name: linux-rrd
+      release-commit: ${{ needs.version.outputs.release-commit }}
     secrets: inherit
 
   build-and-publish-web:
@@ -187,6 +191,7 @@ jobs:
     uses: ./.github/workflows/reusable_build_and_publish_web.yml
     with:
       release-version: ${{ needs.version.outputs.current }}
+      release-commit: ${{ needs.version.outputs.release-commit }}
       concurrency: ${{ github.ref_name }}
       wheel-artifact-name: linux-wheel
       rrd-artifact-name: linux-rrd
@@ -201,21 +206,26 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
+        with:
+          ref: ${{ needs.version.outputs.release-commit }}
 
       - name: Update latest branch
         run: |
           git fetch
           git checkout ${{ github.ref_name }}
           git push --force origin ${{ github.ref_name }}:latest
-          git commit -m "Update docs for ${GITHUB_SHA}"
-          git push origin gh-pages-orphan:gh-pages -f
 
   post-release-version-bump:
     name: "Post-release Version Bump"
     if: inputs.release-type == 'release'
     needs: [version, update-docs, publish-crates, build-and-publish-wheels, build-and-publish-web]
     runs-on: ubuntu-latest
     steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          ref: main
+
       - name: Install dependencies
         run: |
           python3 -m pip install -r scripts/ci/requirements.txt

.github/workflows/reusable_build_and_publish_web.yml

@@ -10,6 +10,10 @@ on:
         description: "Release Version Number (Must match Cargo.toml)"
         type: string
         required: true
+      release-commit:
+        description: "Commit to release"
+        type: string
+        required: true
       wheel-artifact-name:
         description: "Name of the wheel to use when running examples"
         type: string
@@ -33,17 +37,19 @@ jobs:
     steps:
       - name: "Set short-sha"
         id: get-short-sha
-        run: echo "short-sha=$(echo ${{ github.sha }} | cut -c1-7)" >> $GITHUB_OUTPUT
+        run: echo "short-sha=$(echo ${{ inputs.release-commit }} | cut -c1-7)" >> $GITHUB_OUTPUT
 
       - name: "Set full-sha"
         id: get-full-sha
-        run: echo "full-sha=${{ github.sha }}" >> $GITHUB_OUTPUT
+        run: echo "full-sha=${{ inputs.release-commit }}" >> $GITHUB_OUTPUT
 
   build-web:
     runs-on: ubuntu-latest-16-cores
     needs: [get-commit-sha]
     steps:
       - uses: actions/checkout@v3
+        with:
+          ref: ${{ inputs.release-commit }}
 
       - name: Set up Rust
         uses: ./.github/actions/setup-rust