API Review Process.md

Description

Starting from the 5.0, certain areas within the aspnet/AspNetCore repo will require formal API Review process. API changes to the following areas are required to go follow this process:

• area-mvc
  • feature-model-binding
  • feature-razor-pages
  • feature-JSONPatch
  • feature-discovery
  • feature-formatters
  • feature-api-explorer
  • feature-tag-helpers
• area-signalr
• area-hosting

Process

The goal of the API Review process is to ensure that the new APIs are following common patterns and the best practices. Also, it's aimed to help and guide engineers towards better API design decisions. People should feel empowered to submit their APIs for review as besides all the benefits it's also a learning and knowledge sharing experience.

The process is visualized in the below diagram:

1. API review process kicks in after the owner for the issue identifies that the work required for the issue will need an API change or addition. In such cases, the issue owner will handle (either himself/herself, or with the community member who has expressed interest in handling the work) driving a design proposal. When working with a community member, the issue owner is responsible for guiding them to an acceptable design.
2. If the proposed design adds new APIs, mark those issues with the api-suggestion label
3. When the issue owner thinks the proposal is in a good shape, he/she marks the issue with api-ready-for-review label. Also, the @asp-net-api-reviews team should be notified on the issue.
4. The asp-net-api-reviews team will host a weekly API review meeting and will review your proposed API change during the next meeting. If you have an API scheduled for review, you must have a representative in the meeting.
5. Some API reviews can happen through a shorter process. For these situations, simply ping the API review crew for a quicker review, so that it can happen as a conversation.
6. When an API change/suggestion gets approved, the api-approved label should be added to the issue.
7. The owner of the issue is now free to work on the implementation of the proposed API.
8. In case during implementation changes to the original proposal are required, the review should become obsolete and the process should start from the beginning.

API Review Meeting

The API Review meeting should be open to any member of the ASP.NET Core team. And invite will be sent to all the team with pre-booked meeting room and time-slot for these meetings to be hosted. Each API review should include the area owners as mandatory attendees.