feat(scripts): detect modified-but-unreleased dependencies during release

.github/workflows/main.yml

@@ -455,6 +455,46 @@ jobs:
       - name: Check External Type Exposure
         run: cargo +${{ env.RUST_NIGHTLY_EXTERNAL_TYPES }} -Zscript scripts/check-external-types.rs ${{ env.RUST_NIGHTLY_EXTERNAL_TYPES }}
 
+  script-tests:
+    # Pester test suite for the release-related PowerShell scripts
+    # (release-packages.ps1, lib/releasing.ps1, lib/release-flow.ps1).
+    # Always runs (no delta gate) because script-level changes don't move any
+    # Rust crates so delta would mark the PR skippable, but the scripts
+    # themselves may still need validation. Cross-platform matrix mirrors the
+    # platforms developers run the scripts on locally.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      # prep
+      - name: Checkout
+        uses: actions/checkout@v6.0.3
+      - name: Setup
+        # The synthetic-workspace fixture builder shells out to `cargo metadata`,
+        # so Rust must be available even though no Rust code is compiled.
+        uses: ./.github/actions/setup
+        with:
+          rust-toolchain: RUST_LATEST
+
+      - name: Install Pester
+        shell: pwsh
+        run: |
+          $existing = Get-Module Pester -ListAvailable |
+              Sort-Object Version -Descending |
+              Select-Object -First 1
+          if ($null -eq $existing -or $existing.Version -lt [version]'5.7.0') {
+              Install-Module -Name Pester -MinimumVersion 5.7.1 -Force -Scope CurrentUser -SkipPublisherCheck
+          } else {
+              Write-Host "Pester $($existing.Version) already installed; skipping."
+          }
+
+      # execute
+      - name: Run Pester Suite
+        shell: pwsh
+        run: ./scripts/tests/Pester/Run-Tests.ps1
+
   # Single aggregating ("fan-in") status check. Branch protection should
   # require ONLY this context for the workflow jobs below: it succeeds when
   # every dependency either succeeded or was skipped, and fails if any
@@ -500,6 +540,7 @@ jobs:
       - pr-title
       - license-headers
       - external-type-exposure
+      - script-tests
     runs-on: ubuntu-latest
     steps:
       - name: Validate Dependency Results

AGENTS.md

@@ -22,9 +22,17 @@ The spell checker dictionary is in the `.spelling` file, one word per line in ar
 
 ## Changelogs
 
-The changelogs are updated by `scripts/release-crate.ps1` at release time, based on Git history. It is not necessary to make manual edits
+The changelogs are updated by `scripts/release-packages.ps1` at release time, based on Git history. It is not necessary to make manual edits
 to the changelogs, though you are permitted to do so if explicitly instructed.
 
+## Releasing Packages
+
+See [docs/releasing.md](docs/releasing.md) for the release tooling
+reference: glossary (direct/transitive dependent vs dependency, cascade
+direction, change type vs version component, release set, pending
+release, elevation), the cascade-organisation invariants, and the
+workflow for `scripts/release-packages.ps1`.
+
 ## Pull Requests
 
 Pull request titles must follow [Conventional Commits](https://www.conventionalcommits.org/) naming, e.g. `feat(bytesbuf): add new metric` or `fix(cachet): correct eviction logic`.

DEVELOPMENT.md

@@ -47,6 +47,7 @@ After installing the Rust toolchain, we setup repository-specific tooling:
 
 1. Execute `just build` to build the workspace. Verify that the build is successful.
 1. Execute `just test` to execute all tests in the workspace. Verify that all tests pass.
+1. Execute `just test-scripts` to run the Pester suite for the release-related PowerShell scripts. Verify that all tests pass.
 1. Validate that debugging works by opening `crates/tick/examples/tick_basic.rs` and pressing the `Debug` link that appears above `main()`. This should successfully launch the example app under the debugger.
 
 # Linux (WSL) environment setup
@@ -91,6 +92,7 @@ After installing the Rust toolchains, we setup the build target directory for fa
 
 1. Execute `just build` to build the workspace. Verify that the build is successful.
 1. Execute `just test` to execute all tests in the workspace. Verify that all tests pass.
+1. Execute `just test-scripts` to run the Pester suite for the release-related PowerShell scripts. Verify that all tests pass.
 
 ## Setup Visual Studio Code integration
 

README.md

@@ -74,7 +74,7 @@ The `add-crate` script does the following:
   `cargo-doc2readme`](https://crates.io/crates/cargo-doc2readme)
   with a set of appropriate CI badges.
 
-- Creates an empty `CHANGELOG.md` file for the crate, which will later get populated by the `scripts\release-crate.ps1`
+- Creates an empty `CHANGELOG.md` file for the crate, which will later get populated by the `scripts\release-packages.ps1`
   script.
 
 - Creates placeholder `logo.png` and `favicon.ico` files for the crate, which you're expected to replace with legit
@@ -91,9 +91,10 @@ this simple process:
 
 2. Create a branch off of main.
 
-3. Run `./scripts/release-crate.ps1 <crate_name> [new_version]` to bump a crate's version and update the crate's
-   `CHANGELOG.md` file.
-   Run the script many times if you want to release several crates in the same PR.
+3. Run `./scripts/release-packages.ps1 -Packages '<crate_name>@<change_type>'` to update versions and changelogs.
+   The change type for each package is one of `breaking`, `nonbreaking`, `patch`, or an explicit version like
+   `1.0.0`. To release several crates together, list them all in the same `-Packages` argument
+   (for example, `'foo@nonbreaking','bar@patch'`); the script plans the entire release up-front.
 
 4. Create a PR like normal to push changes out.
 
@@ -112,7 +113,7 @@ automation processes:
   always reflects the latest crate documentation.
 
 - The `CHANGELOG.md` file in each crate's directory is auto-generated from the commits to a crate's directory by the
-  `scripts/release-crate.ps1` script.
+  `scripts/release-packages.ps1` script.
 
 To generate documentation locally with all features enabled (including feature-gated items), run: