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 <halter73@gmail.com> * Update docs/APIReviewPrinciples.md Co-authored-by: Stephen Halter <halter73@gmail.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Stephen Halter <halter73@gmail.com>
dotnet · Jan 15, 2025 · a7c124a · a7c124a
1 parent 4fc1a87
commit a7c124a
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 0 deletions.
diff --git a/docs/APIReviewPrinciples.md 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
diff --git 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: