release-deps

/release-deps

What this skill is (and isn't)

Is: the dependency-update phase of release prep. One discovery pass produces a table of every package with current, latest-release, latest-prerelease, proposed, and any policy: block reason. User picks updates per-package. Every audit that can be predicted from the package decisions runs before the apply (analyzer rule-catalog catch-up, polyfill API diff, fuget API surface diff, drift checks). All edits land in one batch. No verification build inside this skill — the verification build is owned by /release orchestrator and runs as a final gate after all release-prep tasks (deps + PublicAPI + milestone-check + test-matrix + release-notes + ad-hoc) so the build sees the cumulative state.

Isn't:

• Not for normal-development dependency updates. Those go through PRs targeted at the affected component.
• Not for adding new packages — adding a new <PackageVersion> is a code change unrelated to release prep.
• Not for the linq2db.t4models self-reference — that gets bumped post-release by release-postpublish step 4 to the just-tagged version, not by this skill.

When to run

• During release prep as task 1 (called by /release orchestrator).
• Manually when the user wants a one-off dependency-update pass outside a release (rare).

Required reading

• .agents/docs/release/nuget-package-notes.md — accrued per-package rules; consulted before rendering the table and before each pre-build audit.
• .agents/docs/release/branch-and-pr.md — branch + PR conventions.
• .agents/docs/ci-tests.md — for the /azp run test-all trigger.

Why this ordering

Every Release build of linq2db.slnx is a 10-25 minute cost. Earlier versions of this skill ran the build first and then reacted to its errors per-package — a Meziantou bump alone could trigger 3-4 build cycles (initial build → disable noisy new rules → re-build → fix one rule's errors → re-build → ...). The new ordering pushes every audit that can be done from package metadata alone to before the apply, batches all consequent file edits, and does not run a verification build at all — that is delegated up to /release orchestrator, which runs one verification build at the very end of release prep, after every other prep task (PublicAPI / milestone-check / test-matrix / release-notes / ad-hoc) has had its turn to mutate the tree. The build then sees the cumulative state in one shot.

If that final build fails on something none of our predictive audits caught, the fix is a follow-up commit on the same PR — but the common case becomes one build per release prep, not one per task.

Procedure

1. Discover

pwsh -NoProfile -File .agents/scripts/release-deps-discover.ps1 -Action discover -Version <ver>

The script:

• Parses <PackageVersion> entries in Directory.Packages.props. Resolves $(PropertyName) references using the file's <PropertyGroup> properties.
• Greps VersionOverride="..." across .csproj / .props (rediscovered each run — locations may shift).
• Identifies shipping vs test-only packages: a package is shipping if any Source/**/*.csproj (excluding Source/LinqToDB.LINQPad/, Source/LinqToDB.CLI/, which are tooling not shipping libs) has a <PackageReference Include="<id>" /> for it.
• Queries https://api.nuget.org/v3/registration5-gz-semver2/<id>/index.json for each unique package — returns listed versions only (skip unlisted — they may be removed/deprecated). Parallel fan-out, cached at .build/.agents/release-<ver>-deps-cache/<id>.json.
• Applies policy:
  • runtime-pin (shipping + Id matches ^(System\.|Microsoft\.Extensions\.|Microsoft\.AspNetCore\.|Microsoft\.Bcl\.) + current is an initial .0 version): keep current. Surface latest-release as a blocked update with reason policy:runtime-pin.
  • shipping-prerelease: if a candidate target version is prerelease, mark the row blocked unless user explicitly overrides.
  • vulnerable: not detected by this discovery pass — surfaced by step 4f's advisory / provenance audit instead.
• Emits a plan JSON at .build/.agents/release-<ver>-deps-plan.json.

Conditional <PackageVersion> entries (TFM-bracketed via Condition="...") are surfaced as separate rows with the condition shown.

2. Render the table

The agent reads the plan and renders one numbered row per package. The table includes packages with available updates blocked by policy — visible so the user can override.

#  Package                          Current        Latest-Rel    Latest-Pre    Proposed   Rule  Notes  Reason
1  Npgsql                           9.0.3          9.0.4         10.0.0-rc.1   9.0.4       —    ?
2  Microsoft.Data.SqlClient         5.2.2          6.0.1         —             6.0.1       ✓    ✓
3  Oracle.ManagedDataAccess (OV)    23.6.1         23.7.0        —             23.7.0      —    ?
4  Microsoft.Extensions.Logging     8.0.0          9.0.5         —             —           —    —      policy:runtime-pin
5  SomeAnalyzer                     1.0.0          —             2.0.0-rc.1    2.0.0-rc.1  —    ?     analyzer-allowed-prerelease
...

Columns:

• (OV) after the Id marks a VersionOverride site (different apply mechanic).
• Rule (✓ / —): does nuget-package-notes.md have a custom rule recorded?
• Notes (✓ / ?): is a release-notes URL recorded?
• Reason: populated only for blocked rows.

3. Selection + per-package walk

Walk every actionable row with the user. Per-package category rules from nuget-package-notes.md may auto-resolve some rows without asking (e.g. *LatestForNuget properties stay pinned, *Latest properties auto-bump to latest X.0.x). For each row that needs a decision:

1. Show release notes between current and target version. If notes-url-known is ✓, fetch the URL via WebFetch (or open it in browser for user reading). Else ask user: "where are release notes for <package>?" — record the URL in nuget-package-notes.md.
2. Ask if any custom update rule applies (e.g. co-bump with another package, post-update codegen rerun, downgrade-allowed-for-compat, fuget API diff procedure, TFM-cap rule, vulnerability pin). On a non-trivial answer, append a structured entry to nuget-package-notes.md (per its schema header). Do not stop the walk for a session reload — the discovery script doesn't re-read this file mid-flow; defer the reload to after commit.
3. Confirm target version (default: the row's Proposed).

Multi-row packages (TFM-conditional + VersionOverride sites) get one ask per package — the decision applies to all of that package's rows. Same for packages whose conditional rows reference a shared <PropertyGroup> property.

Output of this step: a per-package decisions map with version targets + per-package audit flags (which packages need fuget API diff, which need polyfill review, etc.).

4. Pre-build audit phase

Run all audits that can be done from package metadata alone, before any file is edited. Each audit may queue additional file edits (.editorconfig lines, code dedups, etc.) that get batched into the apply step.

4a. Analyzer rule-catalog catch-up

For every analyzer package being bumped (Meziantou.Analyzer, NUnit.Analyzers, Microsoft.CodeAnalysis.Analyzers, AsyncFixer, Lindhart.Analyser., etc.):

1. Fetch the package's release-notes URL between current and target versions.
2. Extract the list of new rule IDs added in that version range (e.g. for Meziantou: MAxxxx entries; for NUnit.Analyzers: NUnitxxxx).
3. For each new rule, ask the user: enable as error, enable as suggestion, or disable (severity = none). Record the choice as a queued .editorconfig edit (numerically ordered insert).
4. First-time-this-package update only: also catch up on missed older rules — diff the package's full rule catalog at target against .editorconfig; for each rule absent from .editorconfig, ask the user the same question. Apply existing exceptions (rules already explicitly enabled or disabled stay).

This replaces the old reactive "build → see what fires → ask per rule → re-build" cycle. Predictive answers from the changelog let the build pass on first try.

4b. Polyfill new-APIs review

For every polyfill package being bumped (Meziantou.Polyfill, etc.):

1. Pull the README diff between current and target (or the package's per-version API list).
2. Extract the list of newly polyfilled APIs.
3. For each new API, search the linq2db codebase for our own polyfill or #if-conditional implementation of the same API. If found, propose deletion of the internal copy (queued code edit).
4. Always show the full new-APIs list to the user even when no internal duplicate exists — they may want to opt in to a new polyfill somewhere.

4c. Fuget API-surface diffs

For every package flagged with the Fuget API-diff procedure in nuget-package-notes.md:

1. Fetch the API-surface diff between current and target from the user's fuget server (URL in external-repos.md).
2. Apply the package's diff exclusions (per-package list under **API-diff exclusions:** in nuget-package-notes.md) — strip those namespaces / types from the rendered diff.
3. Show the filtered diff to the user. They decide: absorb the API change (keep the bump), revert the bump (drop the package from the apply list), or add new exclusions (record in nuget-package-notes.md).

4d. Cross-package drift checks

For every package with a recorded drift-alert rule (e.g. linq2db4iSeries mirrors the linq2db version it targets — alert when drift exists between its target version and the linq2db release we're shipping):

1. Read the drift-check predicate from the package's nuget-package-notes.md entry.
2. Compute the drift (e.g. compare provider-API surface between linq2db <dep-target-version> and the about-to-release linq2db version).
3. Surface to user. They decide: ship anyway, hold the release until the upstream catches up, or pin our consumer to a workable older version.

4e. Other predictive checks

Any package-specific pre-check captured in nuget-package-notes.md (e.g. TFM-raised detection per Lowest-supported-TFM detection) runs here. Outputs are queued edits or user decisions, not file mutations.

4f. Security-advisory / provenance check

A dependency bump is a supply-chain entry point — a compromised, typosquatted, or yanked-then-relisted version pulls hostile code into the shipped product (the LiteLLM infostealer incident is the canonical failure this guards against). For every package being bumped:

1. Check the target version for known vulnerabilities. NuGet surfaces GitHub Advisory data — run dotnet list package --vulnerable --include-transitive against the post-edit tree once the apply lands (or query the advisory feed for the target version during the walk). Any target version carrying a known advisory is a blocking user decision.
2. Watch for provenance red flags the discovery script can't see from version numbers alone: an unexpected package owner / author change between current and target, a version that was unlisted-then-relisted, or a sudden major expansion of the transitive dependency tree.
3. A flagged version is a user decision, not an auto-revert: pin to the last clean version, hold the bump, or accept with the justification recorded in nuget-package-notes.md.

This upgrades the "vulnerable: not detected by discovery" gap from step 1 into an explicit predictive audit. It does not replace the verification build — it runs from package metadata + the advisory feed, before the apply, like the other 4x audits.

5. Batch apply

Apply all queued edits in one batched pass, grouped by file:

• Directory.Packages.props: one batched edit covering every updated <PackageVersion> line + new <PropertyGroup> properties + condition cleanups + TFM-split additions.
• Tests/Tests.T4.Nugets/Directory.Packages.props: separate edit if any of its packages are in scope.
• Each VersionOverride csproj: one edit per file.
• .editorconfig: one edit covering every new rule severity line from step 4a (numerically ordered inserts).
• Any code edits queued from step 4b (polyfill dedups) or other audits.

Show the full diff as a single proposal. Gate on user confirmation before any edits land.

6. Mark deps task done — do not commit, do not push

After step 5's apply lands all queued edits, this skill's interactive work is complete. Update state:

pwsh -NoProfile -File .agents/scripts/release-state.ps1 -Action update -Version <ver> -TaskId 1 -Status done -Annotation "<N updates, M skipped, K blocked>"

Do not commit. The release-prep cycle uses one consolidated commit at the end (made by /release-verify task 6 after the build proves stable). All release-prep tasks — deps / PublicAPI / milestone-check / test-matrix / release-notes / ad-hoc — leave their changes on the working tree of release-prep/<ver> and let /release-verify stage everything together. Reasons:

• One commit means one push, one CI trigger, one PR diff to review. Each task committing separately would create commits whose individual states may not even build (e.g. deps lands an analyzer-rule-disabling .editorconfig but the build proves the disable was wrong; a separate verification commit then has to undo it).
• The orchestrator-level verification (/release-verify) sees the cumulative state and can adjust before commit. Separate task commits force the verification fix into a follow-up commit on top of broken intermediate commits.

Do not push. No deps push happens in this skill. Push is owned by /release-verify.

Do not trigger CI. No CI trigger here. CI fires once after /release-verify pushes the consolidated commit.

7. Hand back to /release orchestrator

The orchestrator records the deps task as [x] and proceeds to the next release-prep task. The worktree carries the deps changes uncommitted forward into the next task.

If a build regression escapes the predictive audits in step 4, /release-verify step 2's reactive walk handles it before commit. There's no need for a deps verification build inside this skill.

Don'ts

• Do not silently update a shipping-package Microsoft.Extensions.* / System.* past its pinned-version policy. The pin exists to keep downstream consumers free of transitive constraints — see issue #3953 referenced in Directory.Packages.props.
• Do not auto-include prerelease versions in shipping packages. Always warn + require explicit re-confirmation.
• Do not edit linq2db.t4models from this skill outside the override case where the user explicitly asks. The default ownership of that bump is /release-postpublish step 4.
• Do not batch multiple unrelated package updates into one review — they're unrelated work and each has its own release-notes / risk profile. Per agent-rules.md → Do not batch code-change reviews. Step 3's per-package walk and step 5's batched apply are the same logical change (one cohesive deps update), so the per-edit-confirmation rule does not split this single apply.
• Do not commit, push, or trigger CI from this skill. All of those are owned by /release-verify after the build proves the consolidated release-prep state is sound.
• Do not run a verification build inside this skill. Trust the predictive audits; the orchestrator's /release-verify step runs the only build of the release-prep cycle.