{"id":18530,"date":"2015-01-08T19:48:00","date_gmt":"2015-01-08T19:48:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/dotnet\/2015\/01\/08\/api-review-process-for-net-core\/"},"modified":"2021-09-30T16:10:43","modified_gmt":"2021-09-30T23:10:43","slug":"api-review-process-for-net-core","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/api-review-process-for-net-core\/","title":{"rendered":"API review process for .NET Core"},"content":{"rendered":"<p>Happy new year! Three weeks ago we published a <a href=\"https:\/\/github.com\/dotnet\/corefx\/issues\/294\">proposal for an API review process<\/a> on GitHub and <a href=\"http:\/\/forums.dotnetfoundation.org\/t\/proposal-for-the-api-review-process\/688\">asked for your feedback<\/a>. The process is now in-place and documented in our <a href=\"https:\/\/github.com\/dotnet\/corefx\/wiki\/API%20Review%20Process\">developer wiki<\/a>.<\/p>\n<h2>Review process<\/h2>\n<p>Our primary goal with this review process is to provide a good balance between OSS agility and ensuring&nbsp;high quality APIs. This requires having a centralized body that can continue to review each and every API.<\/p>\n<p>Here is how we approached defining the process:<\/p>\n<ul>\n<li>  <strong>Designed for GitHub<\/strong>. In order to be sustainable and not be a hurdle for contributors the API review process must feel natural to folks familiar with GitHub.<\/p>\n<\/li>\n<li>\n<p><strong>Efficiency<\/strong>. Performing API reviews requires looping in a set of experts. We want to conduct API reviews in an agile fashion without randomizing the reviewers or community members.<\/p>\n<\/li>\n<li>\n<p><strong>Transparency<\/strong>. We can use the same process for both internal as well as external contributors. This allows contributors to benefit from the results of API reviews even if the implementer isn&#8217;t external.<\/p>\n<\/li>\n<\/ul>\n<p><img decoding=\"async\" src=\"https:\/\/devblogs.microsoft.com\/dotnet\/wp-content\/uploads\/sites\/10\/2015\/01\/API-Review-Process.png\" alt=\"API Review Process\"><\/p>\n<p>GitHub is generally based around the pull-request model. The idea is that contributors perform their changes in their own fork and submit a pull request against our repository.<\/p>\n<p>For trivial code changes, such as typo fixes, we want folks to directly submit a pull request rather than opening an issue. However, for bug fixes or feature work, we want contributors to first start a discussion by creating an issue.<\/p>\n<p>For work that involves adding new APIs we&#8217;d like the issue to contain what we call a <em>speclet<\/em>. The speclet should provide a rough sketch of how the APIs are intended to be used, with sample code that shows typical scenarios. The goal isn&#8217;t to be complete but rather to illustrate the direction so that readers can judge whether the proposal is sound. Here is <a href=\"https:\/\/github.com\/dotnet\/corefx\/issues\/271\">a good example<\/a>.<\/p>\n<p>For more details, take a look at our <a href=\"https:\/\/github.com\/dotnet\/corefx\/wiki\/API%20Review%20Process\">developer wiki<\/a>.<\/p>\n<h2>Review notes<\/h2>\n<p>Today, we&#8217;ve also uploaded a <a href=\"https:\/\/github.com\/dotnet\/apireviews\">new repository<\/a> that we&#8217;ll use to store API review notes publicly. Notes are generally comprised of a text document with high-level notes and a detailed API diff with notes associated with individual APIs.<\/p>\n<p>Yesterday morning, we reviewed some API additions to immutable collections. You find the <a href=\"https:\/\/github.com\/dotnet\/apireviews\/\">corresponding notes here<\/a>. An example of an API diff with associated notes <a href=\"https:\/\/github.com\/dotnet\/apireviews\/\">is also available<\/a>.<\/p>\n<h2>What&#8217;s next?<\/h2>\n<p>Next week, we&#8217;ll plan to perform the first review of the <a href=\"https:\/\/github.com\/dotnet\/corefx\/labels\/api%20addition\">backlog<\/a> that is filled by the community. We&#8217;ll record the session and upload a video as well. While we don&#8217;t necessarily plan to record <em>every<\/em> meeting, we plan on doing it on a regular cadence so that you can take a look at the sausage factory and understand how these reviews look like.<\/p>\n<h2>Summary<\/h2>\n<p>Together with the community we&#8217;ve setup an <a href=\"https:\/\/github.com\/dotnet\/corefx\/wiki\/API%20Review%20Process\">API review process<\/a>. We&#8217;ve also created a new <a href=\"https:\/\/github.com\/dotnet\/apireviews\">GitHub repository<\/a>&nbsp;that will serve as the container for the notes.<\/p>\n<p>Please let us know what you think!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Happy new year! Three weeks ago we published a proposal for an API review process on GitHub and asked for your feedback. The process is now in-place and documented in our developer wiki. Review process Our primary goal with this review process is to provide a good balance between OSS agility and ensuring&nbsp;high quality APIs. [&hellip;]<\/p>\n","protected":false},"author":335,"featured_media":58792,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[685],"tags":[30,51,107],"class_list":["post-18530","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-dotnet","tag-announcement","tag-community","tag-open-source"],"acf":[],"blog_post_summary":"<p>Happy new year! Three weeks ago we published a proposal for an API review process on GitHub and asked for your feedback. The process is now in-place and documented in our developer wiki. Review process Our primary goal with this review process is to provide a good balance between OSS agility and ensuring&nbsp;high quality APIs. [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/18530","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/users\/335"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/comments?post=18530"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/posts\/18530\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media\/58792"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/media?parent=18530"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/categories?post=18530"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/dotnet\/wp-json\/wp\/v2\/tags?post=18530"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}