From a7c124aaf9bebc6969ed91e0daf7928ef67d3e1f Mon Sep 17 00:00:00 2001 From: Artak <34246760+mkArtakMSFT@users.noreply.github.com> Date: Tue, 14 Jan 2025 21:45:04 -0800 Subject: [PATCH] Added APIReviewPrinciples document (#59880) * Added APIReviewPrinciples document * Update docs/APIReviewPrinciples.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/APIReviewProcess.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/APIReviewProcess.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update docs/APIReviewProcess.md * Update docs/APIReviewPrinciples.md Co-authored-by: Stephen Halter * Update docs/APIReviewPrinciples.md Co-authored-by: Stephen Halter --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Stephen Halter --- docs/APIReviewPrinciples.md | 14 ++++++++++++++ docs/APIReviewProcess.md | 4 ++++ 2 files changed, 18 insertions(+) create mode 100644 docs/APIReviewPrinciples.md diff --git a/docs/APIReviewPrinciples.md b/docs/APIReviewPrinciples.md new file mode 100644 index 000000000000..b95bbde54af2 --- /dev/null +++ b/docs/APIReviewPrinciples.md @@ -0,0 +1,14 @@ +# API Review Conventions and Principles + +Welcome to the API Review Conventions and Principles document for the dotnet/aspnetcore repository. This document serves as a comprehensive guide to the conventions and principles that our team has established over time. It is designed to encapsulate our collective knowledge and best practices, ensuring consistency and quality in our API design. + +The primary goal of this document is to provide a reference for our team and contributors, helping them to understand and apply these principles when proposing new APIs. By adhering to these guidelines, we aim to foster a collaborative and informed API review process, ultimately enhancing the robustness and usability of our APIs. + +We encourage you to refer to this document regularly and contribute to its evolution as we continue to refine our API review process. We also encourage you to follow the [.NET framework design guidelines](https://learn.microsoft.com/dotnet/standard/design-guidelines/) for more general guidance not specific to the dotnet/aspnetcore repository. + + +## Principles +- Principle 1 + +## Conventions +- Convention 1 \ No newline at end of file diff --git a/docs/APIReviewProcess.md b/docs/APIReviewProcess.md index 17c522cb2b77..2a8755a54e83 100644 --- a/docs/APIReviewProcess.md +++ b/docs/APIReviewProcess.md @@ -19,6 +19,10 @@ The process is visualized in the below diagram: 1. The owner of the issue is now free to work on the implementation of the proposed API. 1. In case during implementation changes to the original proposal are required, the review should become obsolete and the process should start from the beginning. +## Learnings and growth + +Over time the team will build up certain conventions and principles, that will be useful to establish for future API reviews too. To help with this, the [API Review Principles document](/docs/APIReviewPrinciples.md) document will be used to store such principles and conventions, making them persistent over time. Eventually, it will grow into a good knowledge base that will also help newcomers to learn and be better prepared with designing their APIs. + ## What Makes an issue/PR "ready-for-review"? Before marking an issue as `api-ready-for-review`, make sure that the issue has the following: