Upgrade Packages

Upgrade Packages

Bring all backend, frontend, and GitHub Actions dependencies to their latest versions. The project always runs the latest version of every package. Don't quit, give up, or recommend reverting just because something is non-trivial — research, debug, push through. The only acceptable reasons to skip an upgrade are the permanent exceptions below.

How To Drive The CLI

Every NuGet and npm bump goes through the developer CLI. Run it directly (the Bash hook allows dotnet run --project developer-cli, and the CLI runs its own dotnet/npm subprocesses without tripping the hook):

dotnet run --project developer-cli -- update-packages [--backend|--frontend] [--dry-run] [--exclude <csv>] [--include-major-framework-updates] --quiet

Always pass --quiet. In quiet mode the command prints no tables or banners — only parseable plain-text lines:

<side> <patch|minor|major> <package> <current> -> <new> [<extra>]
<side> restricted <package> <current> (latest <X> is a new major, pinned)
<side> excluded <package> <current>
summary <side> patch=<n> minor=<n> major=<n> excluded=<n> uptodate=<n>

<side> is backend or frontend. restricted lines are the permanent exceptions (pinned to their current major by the CLI). Use a --dry-run --quiet run to plan; parse the major lines to get the package names that need their own commit.

Run the build, format, lint, test, and e2e skills for all verification (never raw dotnet/npm).

Permanent Exceptions

These never move to a new major. The CLI enforces them itself (RestrictedNuGetPackages in developer-cli/Commands/UpdatePackagesCommand.cs), so you do not pass --exclude for them — they show up as restricted lines in the dry-run and are pinned to the latest version within their current major:

• MediatR, FluentAssertions — later majors changed licensing/APIs.
• Microsoft.ApplicationInsights, Microsoft.ApplicationInsights.AspNetCore — the next major drops PageView tracking as part of moving to OpenTelemetry; the codebase uses PageView heavily and that migration is a separate effort.

Note: frontend @microsoft/applicationinsights-* packages are not restricted and upgrade normally. .NET, Node.js, and @types/node stay within their current major unless you pass --include-major-framework-updates; don't cross a framework major as part of a routine package upgrade.

Principles

1. Use update-packages for every bump. Never hand-edit package.json / Directory.Packages.props or run raw npm / dotnet to move a version.
2. The CLI must produce a correct outcome. If it doesn't, fix the CLI in developer-cli/Commands/UpdatePackagesCommand.cs, and commit that fix on its own. Working around a CLI bug by hand is unacceptable — the next person deserves the fix.
3. Order is fixed and never reordered: backend (.NET) first, then frontend, then GitHub Actions last. If the backend is blocked because a new toolchain (a .NET SDK) isn't installed, that install needs sudo/admin — ask the user to run it up front (Workflow step 3) and wait. Never skip ahead to the frontend to "stay busy" while a backend toolchain install is pending.
4. Atomic commits. Trivial bumps (patch + minor) go into one bulk commit per side. Every major — and anything needing a code change, config change, or API rename — gets its own commit with the change.
5. Research majors online. Read the changelog, release notes, and GitHub issues for every major before applying it. If a new major exposes cheap, obvious improvements, adopt them in the same commit. If adoption is non-trivial, ship the upgrade and note the follow-up.
6. Verify smartly, and gate each phase. build + lint per trivial commit; add e2e after majors that touch runtime, build tooling, or i18n; run format whenever code changes or after upgrading formatter/linter tooling. Run a full backend regression with e2e at the end of the backend phase, before the frontend, and a full regression for both sides at the very end. Fold any fix into the commit that caused it (see Fixing A Regression).
7. Push through. When an upgrade misbehaves, figure out why. Reverting is the last resort, only after evidence the version is genuinely unusable.

Fixing A Regression

When a regression run fails, the bad change belongs in an earlier commit — fold the fix there, don't tack a loose fix on the end. The branch isn't pushed yet, so rewriting local history is safe. Two patterns by cause:

• The upgrade is fine but code must adapt — make the code/config change, then fold it into the commit that introduced the breakage: git commit --fixup=<offending-commit> followed by git rebase --autosquash --interactive <base>.
• One package in a bulk commit is the culprit — pull just that package out of the bulk so the bulk stays green (re-run the bulk with that package added to --exclude, or drop its version bump from the bulk commit via a fixup), then give it its own commit on top with the code change it needs — exactly like a major.

Either way, keep every commit independently green and bisectable, and never move to the next phase with a red suite — the fix-up happens in the phase that caused it.