From 4e3fb283b588d687ef253cad9c4977214b6b326b Mon Sep 17 00:00:00 2001 From: Adrian Hall Date: Mon, 8 Apr 2019 07:42:33 -0700 Subject: [PATCH] Update of terminology (#287) --- README.md | 14 +++++++++++++- docs/ReviewProcess.md | 6 +++--- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9c9937b9e..340c7db1e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,21 @@ # Azure SDK -The Azure SDK delivers a platform for developers to leverage the wide variety of Azure services in their language of choice. The source for the libraries exists for the most part in repositories for each language. This repository is meant to be a jumping off point into those language specific repositories. Issues related to a specific language should be opened in the corresponding repository but cross cutting issues can be opened in this repository. +The Azure SDK delivers a platform for developers to leverage the wide variety of Azure services in their language of choice. The source for the client libraries exists for the most part in repositories for each language. This repository is meant to be a jumping off point into those language specific repositories. Issues related to a specific language should be opened in the corresponding repository but cross cutting issues can be opened in this repository. | [.NET](https://github.com/Azure/azure-sdk-for-net) | [Java](https://github.com/Azure/azure-sdk-for-java) | [Python](https://github.com/Azure/azure-sdk-for-python) | [JavaScript](https://github.com/Azure/azure-sdk-for-js) | [Go](https://github.com/Azure/azure-sdk-for-go) | +## Terminology + +- **SDK**: Software Development Kit. This refers to the entire Azure SDK for a single language, itself broken up into numerous Azure SDK _Client Libraries_ (as defined below). + +- **Client Library**. This refers to a library (and associated tools, documentation, and samples) that customers/developers use to ease working with an Azure service. There is often one client library per service and per programming language. Sometimes a single client library will contain the ability to connect to multiple services. Each client library is published separately to the appropriate language-specific package repository. These releases are performed exclusively by the Azure SDK engineering systems team. Customers/Developers consume and use each client library separately as necessary to solve their use case. + +- **Package**. This refers to a client library after it has been packaged for distribution for customer-developers to consume. Examples are: + - A Nuget package for a .NET client library + - A Maven package for a Java library + - An NPM package for a JavaScript library + - A Python wheel for a Python library + ## Azure SDK Design Guidelines - [.NET](https://azuresdkspecs.z5.web.core.windows.net/DotNetSpec.html) ([template](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/template/Azure.Template)) diff --git a/docs/ReviewProcess.md b/docs/ReviewProcess.md index 7f1df7394..0f388dbef 100644 --- a/docs/ReviewProcess.md +++ b/docs/ReviewProcess.md @@ -41,15 +41,15 @@ If you have a prototype of your APIs, depending on the language the APIs are for To request a review: -1. [Submit an issue](https://github.com/azure/azure-sdk/issues). If the service is pre-release, use a private repository. For escalations, email the [review board](mailto:adparch@microsoft.com) only after submitting the issue. +1. [Submit an issue](https://github.com/azure/azure-sdk/issues). If the service is pre-release, use the private repository. For escalations, email the [review board](mailto:adparch@microsoft.com) only after submitting the issue. - Ensure you provide all information (or direct links to the information) for ease of review. 2. The ADP Review Board PM will schedule a 1:1 with a language architect to provide initial guidance. It is important that this initial review happen **BEFORE** any major development happens. - Get the ADP Reviews happening in concert with your design process for best results. 3. If needed, a review with the entire review board will be scheduled. The cases where this is necessary include: - - This is a completely new SDK. + - This is a completely new client library. - The reviewing language architect feels there are cross-cutting concerns. - Exceptions from the guidelines are being sought (such as additional dependencies) 4. After reviews are completed, the review team will publish recommendations. -It is normal to have multiple API reviews as the development of the SDK progresses. +It is normal to have multiple API reviews as the development of the client library progresses.