Skip to content

docs(instructions): add release decision policy for batched changes#13

Merged
rcappello merged 1 commit into
mainfrom
docs/release-decision-policy
Jun 23, 2026
Merged

docs(instructions): add release decision policy for batched changes#13
rcappello merged 1 commit into
mainfrom
docs/release-decision-policy

Conversation

@rcappello

Copy link
Copy Markdown
Owner

Summary

Adds a Release decision policy section to .github/instructions/project.instructions.md so agents (and humans) have a clear, written rule for deciding whether a batch of merged changes — typically a stack of Dependabot PRs — warrants proposing a version bump and a new release.

What it adds

  • Guiding principle: a change warrants a release only if it can affect what end users install from the Marketplace. Pure build-time, CI, lockfile, or developer-tooling changes do not.
  • VS Code client matrix (src/vscode/) — classifies each kind of change (TypeScript, runtime dependencies, engines.vscode, NLS strings, dev-dependencies, transitive lockfile bumps, docs / CI, …) as release-worthy (Yes) or not (No), and suggests the bump level.
  • VS 2026 client matrix (src/vs2026/) — same shape, accounting for which NuGet packages actually ship in the VSIX (runtime PackageReference vs PrivateAssets="all" / analyzers / build-only).
  • Agent workflow on a batch of merges — classify every PR, recommend skipping the release if everything lands in the "No" rows, otherwise propose the highest required bump level citing the triggering PR(s) and the exact version source-of-truth file.
  • Reinforces the existing Must rule: never edit version files, publish, push tags, or run release workflows without an explicit plan or developer instruction — only propose.

Why

We currently get long-running Dependabot stacks (esbuild major bumps, transitive shell-quote / form-data / undici / markdown-it / js-yaml security alerts) plus occasional functional changes. Without an explicit policy, agents were inconsistent — sometimes proposing a release for a dev-only lockfile bump, sometimes skipping a real runtime dependency upgrade. The matrices make the decision deterministic and reviewable.

Out of scope

  • Pure documentation change — no source / build / CI / version file touched.
  • Doesn't itself bump any version or trigger any release workflow.

Adds a 'Release decision policy' section to .github/instructions/project.instructions.md describing how to decide whether a batch of merged changes (typically Dependabot PRs) warrants proposing a version bump.

Introduces per-client matrices (VS Code, VS 2026) classifying changes as release-worthy (Yes) or not (No) based on whether they actually reach the published VSIX, and codifies the agent workflow on a batch of merges (classify, recommend bump only when any 'Yes' row triggers, never edit version files without explicit developer confirmation).
@rcappello rcappello merged commit 5da173f into main Jun 23, 2026
4 checks passed
@rcappello rcappello deleted the docs/release-decision-policy branch June 23, 2026 14:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant