Description
openedon Jun 22, 2020
Thank you for starting the process for approval of the client library for your Azure service. Thorough review of your client library ensures that your APIs are consistent with the guidelines and the consumers of your client library have a consistently good experience when using Azure.
** Before submitting, ensure you adjust the title of the issue appropriately **
To ensure consistency, all Tier-1 languages (C#, TypeScript, Java, Python) will generally be reviewed together. In expansive libraries, we will pair dynamic languages (Python, TypeScript) together, and strongly typed languages (C#, Java) together in separate meetings.
The Basics
- Service team responsible for the client library: Azure Dedicated
- Link to documentation describing the service: https://docs.microsoft.com/en-us/rest/api/avs/
- Contact email (if service team, provide PM and Dev Lead): Divya Kamath, Cameron Taggart
About this client library
- Name of the client library: AVS
- Languages for this review: JavaScript, Python, Go, .NET, Java
- Link to the service REST APIs: Microsoft.AVS 2019-08-09-preview
Artifacts required (per language)
We use an API review tool (apiview) to support .NET and Java API reviews. For Python and TypeScript, use the API extractor tool, then submit the output as a Draft PR to the relevant repository (azure-sdk-for-python or azure-sdk-for-js).
.NET
- Artifact: https://www.nuget.org/packages/Microsoft.Azure.Management.Avs/1.0.0-preview.1
- Upload DLL to apiview. Link: review from local build
- Link to samples for champion scenarios:
Java
- Artifact: https://search.maven.org/artifact/com.microsoft.azure.avs.v2019_08_09_preview/azure-mgmt-avs/1.0.0-beta/jar
- Upload JAR to apiview. Link: review
- Link to samples for champion scenarios:
Python
- Artifact: https://pypi.org/project/azure-mgmt-avs/0.1.0/
- Upload the api as a Draft PR. Link to PR: release for mgmt vmware azure-sdk-for-python#12003
- Link to samples for champion scenarios:
TypeScript
- Artifact: https://www.npmjs.com/package/@azure/arm-avs
- Bug in api-extractor preventing use: [api-extractor] Support "import * as __ from __" for local paths microsoft/rushstack#1029
- Upload output of api-extractor as a Draft PR. Link to PR: release for arm vmware azure-sdk-for-js#9502
- Link to samples for champion scenarios:
Go
- Artifact: https://github.com/Azure/azure-sdk-for-go/tree/master/services/preview/vmware/mgmt/2019-08-09-preview/vmware
- will be renamed from vmware to avs
Champion Scenarios
A champion scenario is a use case that the consumer of the client library is commonly expected to perform. Champion scenarios are used to ensure the developer experience is exemplary for the common cases. You need to show the entire code sample (including error handling, as an example) for the champion scenarios.
- Champion Scenario 1:
- Describe the champion scenario: create a private cloud
- Estimate the percentage of developers using the service who would use the champion scenario: 75%
- Link to the code sample: C# create private cloud
_ Repeat for each champion scenario _
Examples of good scenarios are technology agnostic (i.e. the customer can do the same thing in multiple ways), and are expected to be used by > 20% of users:
- Upload a file
- Update firmware on the device
- Recognize faces in an uploaded image
Examples of bad scenarios:
- Create a client (it's part of a scenario, and we'll see it often enough in true champion scenarios)
- Send a batch of events (again, part of the scenario)
- Create a page blob (it's not used by enough of the user base)
Agenda for the review
A board review is generally split into two parts, with additional meetings as required
Part 1 - Introducing the board to the service:
- Review of the service (no more than 10 minutes).
- Review of the champion scenarios.
- Get feedback on the API patterns used in the champion scenarios.
After part 1, you may schedule additional meetings with architects to refine the API and work on implementation.
Part 2 - the "GA" meeting
- Scheduled at least one week after the APIs have been uploaded for review.
- Will go over controversial feedback from the line-by-line API review.
- Exit meeting with concrete changes necessary to meet quality bar.
