skills.rest
microsoft
microsoftOFFICIAL
Explore all skills by this author →
Website𝕏@OpenAtMicrosoftGitHub

api-changes

Reviews customer-facing API changes in Fluid Framework API report diffs for release tags, breaking changes, and changesets.

4.9k|585|Updated Aug 22, 2019
Search Tags:#deprecation#changeset#api extractor#release tags#fluid framework#API review#Breaking Changes
One-click install
npx skills add https://github.com/microsoft/FluidFramework --skill api-changes
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-changes
Source: https://github.com/microsoft/FluidFramework/tree/main/.claude/skills/api-changes
Command: npx skills add https://github.com/microsoft/FluidFramework --skill api-changes

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When API report .md files change in the Fluid Framework repo, contributors must follow strict governance: release tag assignment, API Council review, breaking change classification, deprecation process, and changeset creation. This Skill walks through each requirement so nothing is missed before merging.

Core Features & Use Cases

  • API Diff Analysis: Compares api-report .md files against the resolved comparison base and summarizes additions, removals, signature changes, and tag promotions per package.
  • Governance Checks: Verifies release tags (@public/@beta/@alpha/@internal), TSDoc documentation, export reachability from package entrypoints, and whether API Council approval is required.
  • Breaking Change & Deprecation Guidance: Classifies breaking changes by tag tier, explains staging branch and timing rules, validates deprecation checklists, and drafts a changeset via pnpm flub changeset add.
  • Use Case: After regenerating API reports for a PR that adds a new @beta export, run this Skill to confirm the export is reachable from the package entrypoint, documented, and accompanied by a proper changeset before requesting review.

Quick Start

Review my current API report changes and tell me whether they need API Council approval, a changeset, or breaking-change staging.

Frequently Asked Questions about api-changes

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review API report changes before merging a Fluid Framework PR?▼

Diff the api-report .md files against the resolved comparison base, including untracked reports, then classify each change as addition, removal, signature change, or tag promotion. The Skill builds a summary table and checks tags, docs, council review, and changesets.

Which release tag should I use for a new Fluid Framework API?▼

Use @public only for final stable shapes, @beta for feedback-seeking APIs on a path to public, @alpha for experimental APIs, and @internal for framework-only surface. When in doubt choose @alpha since promotion is easier than demotion.

When is API Council approval required for API changes?▼

Changes to @public, @legacy @public, @beta, or @legacy @alpha surfaces require API Council approval, with fluid-cr-api automatically assigned as a required reviewer. @alpha-only and @internal-only changes do not require approval.

Can I make a breaking change to a @beta API in Fluid Framework?▼

Breaking @beta or @legacy @alpha changes may only land in minor versions that are increments of 10, such as 2.10 or 2.20. The PR must be staged on a test/breaks/client branch and held until the break window opens.

Why does API Extractor report ae-missing-release-tag?▼

The error occurs when a new export lacks a release tag such as @public, @beta, @alpha, or @internal. Add the appropriate TSDoc release tag to every new export so API Extractor can classify the API surface.

Do all customer-facing API changes need a changeset?▼

Yes, additions, modifications, deprecations, tag promotions, and removals all require a changeset. Create one with pnpm flub changeset add --empty, then fill in affected packages with a minor bump and the appropriate section such as feature, deprecation, or breaking.

Related Skills

Explore More Software Engineering Skills→
kage1020kage1020

diff-report

Analyze branch changes and generate a five-section Markdown diff report.

Community
Intermediate
HomericIntelligenceHomericIntelligence
18

pr-cleanup

Squash commits, rebase onto main, and verify CI status for GitHub pull requests.

Official
Intermediate
elasticelastic
21.2k

branch-readiness-checks

Run diff analysis, linting, type checking, and unit tests on affected packages.

Official
Advanced
module-federationmodule-federation
2.6k

changeset-pr

Create and verify `.changeset/*.md` files for pull requests in a monorepo.

Official
Advanced