api-baselines

api-baselines

User-triggered workflow to regenerate the CompatibilitySuppressions.xml baselines that ApiCompat uses to track intentional public-API changes. Equivalent to running UpdateBaselines.cmd at the repo root, plus policy checks.

When to run

Only when the user explicitly invokes this skill or asks to refresh / update the API baselines. Do not run it as part of unrelated work — regenerating these files masks real API breakages.

Steps

1. Choose the branch

Check the current branch (git rev-parse --abbrev-ref HEAD).

• If the current branch is master: stop and ask the user where to land the change. Refreshing baselines on master directly is not appropriate. Offer to create a new branch infra/refresh-api-baselines from origin/master (per Creating a new branch in .agents/docs/agent-rules.md). Wait for confirmation.

• If the current branch is not master: ask the user whether to:

  1. Refresh baselines on the current branch, or
  2. Create a new branch infra/refresh-api-baselines from origin/master (per the agent-rules branching workflow — git fetch origin master, handle dirty tree by asking, then branch).

  Wait for the user's choice before proceeding.

• Exception: when the current branch matches release-prep/<version> (the canonical name from branch-and-pr.md), the release-prep flow is the canonical context. Refresh on the current branch without asking — invoked from /release-verify step 4, the consolidated-commit pattern requires baselines to land on the prep branch alongside the rest of the prep changes.

Do not regenerate anything until the branch decision is made.

2. Delete existing suppression files

Equivalent to DEL /S Source\CompatibilitySuppressions.xml from UpdateBaselines.cmd. Find every CompatibilitySuppressions.xml under Source/ (use Glob: Source/**/CompatibilitySuppressions.xml) and delete each one.

3. Regenerate baselines

Run from the repo root (use -p: not /p: — on Git Bash / MSYS, /p:... is path-mangled into a Windows path and MSBuild rejects it with MSB1009: Project file does not exist):

dotnet pack -p:ApiCompatGenerateSuppressionFile=true

This re-runs ApiCompat across all packable projects and writes fresh CompatibilitySuppressions.xml files next to each project that has API differences against its baseline package.

If the command fails, surface the failure and stop. Do not proceed to the policy check on partial output.

A non-zero exit is not always a baseline-generation failure. dotnet pack packs every packable project, so an unrelated project can fail the overall command (exit 1) after ApiCompat has already written the suppression files — e.g. a disk-space error packing the CLI's per-RID nupkgs, or benign Could not resolve reference 'FSharp.Core.dll' / 'System.Security.Permissions.dll' ApiCompat ref-resolution warnings. Before treating exit-1 as fatal, Grep the pack log for a per-target Successfully wrote compatibility suppressions to '…' line for each Source/**/CompatibilitySuppressions.xml you expect; if every expected target wrote, the baselines are valid and you may proceed to the policy check (note the unrelated failure to the user). Stop only when that success line is absent for a target. (Surfaced syncing PR #5468: pack exited 1 on a CLI RID-pack disk-space error after both LinqToDB and LinqToDB.Scaffold suppressions had written.)

Pre-existing analyzer errors trap. dotnet pack runs a Release build, which (per Directory.Build.props) enables RunAnalyzersDuringBuild=true + EnforceCodeStyleInBuild=true. Combined with the repo's dotnet_analyzer_diagnostic.severity = error default in .editorconfig, this turns IDE-style suggestions (IDE0066, IDE0078, IDE2003, etc.) into hard build errors. CI's test-all toggles RunAnalyzersDuringBuild=false via the with_analyzers pipeline variable, so master can land code that fails this local Release build without anyone noticing.

Pack catches strictly more analyzer errors than dotnet build -c Release. Empirically verified during 6.3.0 prep: dotnet pack emitted 9078 MA0177 errors on the prep tree, while dotnet build linq2db.slnx -c Release of the same tree emitted 0. Same Release config, same .editorconfig. Suspected cause: pack invokes additional analyzer paths (perhaps for nupkg content / XML doc validation) that plain build skips. Treat dotnet pack as the strictest analyzer gate in the repo — plain dotnet build -c Release is not a sufficient analyzer pre-check for a pack invocation. If you want to pre-validate before invoking this skill, use dotnet pack -p:RunAnalyzersDuringBuild=false to bypass analyzers entirely and re-run with analyzers enabled when ready to walk findings.

When this skill is invoked standalone (outside the release-prep flow) and trips on such errors:

• Canonical path: fix or disable the rules per /release-verify step 2a's flow.
• Quick workaround: re-run with -p:RunAnalyzersDuringBuild=false to bypass — ApiCompat itself doesn't need analyzers to regenerate suppressions, just a clean compile.

When invoked from /release-verify (as its step 4), the analyzer-error walk has already happened in /release-verify's step 2a, so this trap shouldn't fire.

4. Inspect the diff for policy violations

After regeneration, diff the suppression files against HEAD:

git diff -- 'Source/**/CompatibilitySuppressions.xml'

Pair adds against removes first. Before classifying anything, walk through the diff and pair each added <Suppression> block with a removed block that has the same (DiagnosticId, Target, Left, Right) tuple. These are re-orderings inside the file (the regenerator may sort entries differently than the previous run) and represent no semantic change — drop them from both the "added" and "removed" sets. Apply the namespace check only to the residual additions.

For every residual added <Suppression> block (lines beginning with + that contain a <Target> element and have no matching removal), extract the symbol DocId from the <Target> value. The DocId has the form <kind>:<namespace>.<name>[(...)] where <kind> is one of T, M, P, F, E, N.

Determine the containing namespace:

• For T:Ns.Sub.TypeName → namespace is Ns.Sub.
• For M:Ns.Sub.TypeName.Method(...) / P: / F: / E: → strip the trailing (...) parameter list (if any), then drop the last two segments (member name + containing type). Namespace is what remains.
• For N:Ns.Sub → namespace is the value itself.
• For nested types (T:Ns.Outer+Inner or T:Ns.Outer.Inner where Inner is nested) — only the leading namespace segments matter; if in doubt, treat the longest leading dotted prefix that appears before the first PascalCase type-looking segment as the namespace. When ambiguous, prefer flagging over silently allowing.

A change is policy-allowed iff the namespace equals LinqToDB.Internal or starts with LinqToDB.Internal.. Any other namespace is a policy violation — this matches the rule that /review-pr applies per .agents/docs/api-surface-classification.md, so the two skills stay consistent about what "public API change" means.

Also consider removed <Suppression> blocks (lines beginning with -): a removed suppression usually just means a previously-broken API was fixed or removed and no longer needs suppression. These are informational, not violations — do not block on them, but mention them in the summary if any non-LinqToDB.Internal.* ones disappeared.

5. Report and gate on policy violations

Compose a summary in this shape:

API baseline refresh — diff summary

Files changed:
  <list of CompatibilitySuppressions.xml paths with +N/-M counts>

Allowed (LinqToDB.Internal.*):
  +N suppressions added
  -M suppressions removed

Policy violations (non-LinqToDB.Internal.* changes):
  + <DiagnosticId> <Target>          (file: <relative path>)
  + <DiagnosticId> <Target>          (file: <relative path>)
  ...

If there are no policy violations, stop here and report success — the refresh is done. The user can decide separately whether to commit (per the repo's commit rules — never auto-commit).

If there are policy violations, end the report with this exact warning, then ask for explicit approval:

⚠️ Changes to public APIs outside the LinqToDB.Internal.* namespace are against project policy in general and should be allowed only for major release changes. Review the list above carefully.

Do you want to approve these changes and keep the regenerated baselines, or revert them?

Wait for the user's response.

• If the user approves: leave the regenerated files in place and report done. Do not commit.
• If the user rejects / asks to revert: restore the prior baselines with git checkout -- 'Source/**/CompatibilitySuppressions.xml' (and git clean -f for any newly-created suppression files that didn't exist before — check git status first to identify them). Confirm the working tree matches HEAD for these paths after the revert.

6. Do not commit, push, or open a PR

Per .agents/docs/agent-rules.md → Git commit rules / Push to remote rules / Pull request rules, all of those actions need their own explicit user request. This skill's job ends after the diff is reviewed and either kept or reverted.