API Review

Author an API review issue

Create a separate ASP.NET Core API proposal issue from the originating issue and implementation changes.

Inputs

Gather:

• Originating issue — the issue or feature request that prompted the API change, including all comments
• Implementation pull request or commits — the proposed implementation and its public API changes, especially changes to PublicAPI.Unshipped.txt

Present a checklist of the available inputs. If either input is missing, use the user-input tool to request it before drafting sections that depend on it.

Workflow

1. Gather the evidence. Read the originating issue and all comments, then inspect the implementation pull request, commits, and diff. Account for every changed public or protected type, member, signature, default, or convention. Artifact: a checklist containing the originating issue and implementation source. Check: both sources are available and every public API change is represented.

2. Draft the proposal. Fill each section of the issue body template using the section guidelines:

   • Background and Motivation
   • Usage Examples
   • Proposed API
   • Alternative Designs, when available
   • Risks, when available

   Background and Motivation, Usage Examples, and Proposed API are required. Before writing N/A for Alternative Designs or Risks, ask the user one focused question for each optional section whose information is not present in the originating issue or implementation changes.

3. Add source justifications. At the end of the issue body, map every substantive claim to a quote from the originating issue or implementation changes:

   <<CONTENT>>: "<<QUOTE FROM SOURCE>>"
   

4. Check the draft. Verify:

   • The background gives reviewers outside the feature area enough context
   • The complete API proposal is in ref-assembly diff format
   • The originating issue and implementation pull request or commits are linked
   • Larger changes include proportionate explanation
   • Usage examples demonstrate the intended consumption
   • Alternative designs are documented when available; otherwise the section is N/A
   • Risks and breaking changes are documented when available; otherwise the section is N/A
   • A champion is identified for the API review meeting

5. File a separate issue. Create an issue in dotnet/aspnetcore with:

   • A concise title prefixed with [API Proposal]
   • The completed issue body
   • The api-suggestion and api-proposal labels
   • The Feature issue type when available

   Use the native issue-creation tool when available so the user can confirm the operation. If issue creation is unavailable, provide the ready-to-file title, body, labels, and issue type, and state that the issue was not filed.

6. Link the pull request. Add the API proposal issue link to the implementation pull request without removing its existing description.

Rules

• Do not invent information. Every statement must come from the originating issue or implementation changes. General C# and API knowledge may interpret evidence but must not create missing section content.
• If the evidence is insufficient for a required section, request the missing information. For Alternative Designs and Risks, ask the user one focused question per section; write N/A only when they confirm there is none.
• The Proposed API section must use ref-assembly diff format with complete namespaces and type declarations.
• PublicAPI.Unshipped.txt tracks compatibility but does not grant API approval.
• API review may happen before, during, or after implementation. Pull request readiness and merge do not require api-approved.
• The API proposal issue must have the api-approved label covering the final implemented API shape before the API is included in an RTM release.
• If implementation changes the proposed or previously approved shape, update the proposal and return it to API review before the API is included in an RTM release.
• Notify @dotnet/aspnet-api-review when applying api-ready-for-review. A representative must attend the API review meeting.

Completion

The task is complete when a separate API proposal issue exists with the required title, body, labels, source links, and implementation pull request backlink. If a tool or missing input blocks creation, report the exact blocker and leave a complete ready-to-file draft.

References

• Section guidelines: references/section-guidelines.md
• Issue body template: assets/issue-template.md