From af9f6a04cc9851136aadedf197929821521a00c0 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Fri, 27 May 2022 09:21:45 -0700 Subject: [PATCH 1/6] Add CONTRIBUTING.md --- CONTRIBUTING.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000000..16f4a63e9a3e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,94 @@ +# Contributing + +This file provides general guidance for developers that are creating or updating REST API definitions for Azure. + +## Table of Contents + + + + +- [Design Guidelines](#design-guidelines) +- [Coding Style](#coding-style) +- [Directory Structure](#directory-structure) +- [Pull Requests](#pull-requests) +- [Adding a new service](#adding-a-new-service) +- [Running tests](#running-tests) + * [Unit tests](#unit-tests) + * [Integration tests](#integration-tests) +- [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11) +- [Additional Resources](#additional-resources) + + + +## Reporting problems + +If you discover a problem with a REST API document in this repo, feel free to [open an issue](https://github.com/Azure/azure-rest-api-specs/issues/new). But please do not report issues with service behavior / functionality in this repo. + +When opening an issue, please clearly describe the problem including which REST API definition is in error and what elements of the definition are incorrect or missing. + +## Avoid Breaking Changes + +The first rule for Azure REST APIs is to avoid breaking changes in GA'd APIs. The [Azure Breaking Changes Policy](aka.ms/AzBreakingChangesPolicy) is a formal description of what changes are considered breaking changes. This rule trumps adherence to Design Guidelines, Coding Style, etc. + +## Design Guidelines + +Azure REST APIs should conform to the [Azure REST API Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md). + +There is a [YouTube video series](https://www.youtube.com/watch?v=9Ng00IlBCtw) by Jeffrey Richter that describes the guidelines in detail. + +Another resource is the [Considerations for Service Design](https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md), which is an introduction to REST API design mainly for services that are just getting started. + +### Exceptions for consistency within a service + +There are situations where a service has GA'd their API with design patterns that do not follow our guidelines and it would be a breaking change to adopt the API design in the guidelines. +Because the first rule is to avoid breaking changes and because we want APIs to be consistent within a service, these design patterns are considered the standard for that service and should be followed in all subsequent (non-breaking) versions of that service's REST API. + +## Coding Style + +REST APIs for Azure should be defined using the [OpenAPI v2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) format. + +The REST API should also adhere to the conventions documented in the [Azure API Style Guide](https://github.com/Azure/azure-api-style-guide/blob/main/openapi-style-guide.md). + +You can use the [Spectral linter](https://meta.stoplight.io/docs/spectral/674b27b261c3c-overview) with our [Spectral ruleset](https://github.com/Azure/azure-api-style-guide#how-to-use-the-spectral-ruleset) to check conformance with OpenAPI v2 and the Style Guide. + +## Directory Structure + +See the [README.md][./README.md] for a description of the directory structure to use when adding files to this repo. + +## Pull Requests + +If you want to contribute to the repository, follow these steps: + 1. Fork the repository and create a new branch for your changes. + 2. If you are introducing a new api-version, create a new directory for that api-version and copy all the files from the previous version into the new directory. Make this the very first commit in your branch and then make your changes in subsequent commits. + 3. Use the [linting tools](#coding-style) to check your changes for compliance with the OpenAPI v2 standard, the Azure REST API Guidelines and that Azure API Style Guide. + 4. Push to your fork and submit a pull request to the **main** branch using either the "control plane" or "data plane" PR template -- the main PR template lets you select which one. + 5. Resolve any issues flagged by the [Pull Request checks](#pull-request-checks). + 6. Contact the ARM API Review board or Azure API Stewardship team to request PR review. + +## Pull Request checks + +Every PR in this repo will go through a series of PR checks, including: + +- Breaking Changes - checks for incompatible changes in an existing api-version +- Cross Version Breaking Changes - checks for changes in a new api-version that are incompatible with prior versions +- LintDiff - checks the new or changed portions of the API for compliance with the Azure REST API Guidelines and API Style Guide +- Avocado - checks that new or changed files comply with the directory structure convention for this repo. +- Model Validation - +- Semantic Validation - +- LintRPaaS - +- ApiReadiness - +- PoliCheck - +- CredScan - +- SpellCheck - +- PrettierCheck - +- SDK Breaking Change - + +When any of these PR checks fails it will post a comment to the PR with links to information on how to resolve the problem. From 061c4252338a379b99fd9b211a4034f4da29bc7f Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Tue, 31 May 2022 08:23:13 -0500 Subject: [PATCH 2/6] Apply suggestions from PR review Co-authored-by: Heath Stewart --- CONTRIBUTING.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 16f4a63e9a3e..4d2b8abcf235 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,13 +4,9 @@ This file provides general guidance for developers that are creating or updating ## Table of Contents @@ -36,7 +32,7 @@ When opening an issue, please clearly describe the problem including which REST ## Avoid Breaking Changes -The first rule for Azure REST APIs is to avoid breaking changes in GA'd APIs. The [Azure Breaking Changes Policy](aka.ms/AzBreakingChangesPolicy) is a formal description of what changes are considered breaking changes. This rule trumps adherence to Design Guidelines, Coding Style, etc. +The first rule for Azure REST APIs is to avoid breaking changes in Generally Available (GA'd) APIs. The [Azure Breaking Changes Policy](aka.ms/AzBreakingChangesPolicy) is a formal description of what changes are considered breaking changes. This rule trumps adherence to Design Guidelines, Coding Style, etc. ## Design Guidelines @@ -69,7 +65,8 @@ If you want to contribute to the repository, follow these steps: 1. Fork the repository and create a new branch for your changes. 2. If you are introducing a new api-version, create a new directory for that api-version and copy all the files from the previous version into the new directory. Make this the very first commit in your branch and then make your changes in subsequent commits. 3. Use the [linting tools](#coding-style) to check your changes for compliance with the OpenAPI v2 standard, the Azure REST API Guidelines and that Azure API Style Guide. - 4. Push to your fork and submit a pull request to the **main** branch using either the "control plane" or "data plane" PR template -- the main PR template lets you select which one. + 4. Push to changes to the branch in your fork until the changes are ready to be integrated. + 5. Rebase your branch if needed to incorporate any changes to **main** and submit a pull request to the **main** branch using either the "control plane" or "data plane" PR template -- the main PR template lets you select which one. 5. Resolve any issues flagged by the [Pull Request checks](#pull-request-checks). 6. Contact the ARM API Review board or Azure API Stewardship team to request PR review. From bed0a9fe940d753bb51f1526b2b09642cf00d585 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Tue, 28 Jun 2022 18:01:24 -0700 Subject: [PATCH 3/6] Apply suggestions from PR review Co-authored-by: Weidong Xu --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d2b8abcf235..f6c3c5223664 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ When opening an issue, please clearly describe the problem including which REST ## Avoid Breaking Changes -The first rule for Azure REST APIs is to avoid breaking changes in Generally Available (GA'd) APIs. The [Azure Breaking Changes Policy](aka.ms/AzBreakingChangesPolicy) is a formal description of what changes are considered breaking changes. This rule trumps adherence to Design Guidelines, Coding Style, etc. +The first rule for Azure REST APIs is to avoid breaking changes in Generally Available (GA'd) APIs. The [Azure Breaking Changes Policy](https://aka.ms/AzBreakingChangesPolicy) is a formal description of what changes are considered breaking changes. This rule trumps adherence to Design Guidelines, Coding Style, etc. ## Design Guidelines @@ -57,7 +57,7 @@ You can use the [Spectral linter](https://meta.stoplight.io/docs/spectral/674b27 ## Directory Structure -See the [README.md][./README.md] for a description of the directory structure to use when adding files to this repo. +See the [README.md](./README.md) for a description of the directory structure to use when adding files to this repo. ## Pull Requests @@ -65,7 +65,7 @@ If you want to contribute to the repository, follow these steps: 1. Fork the repository and create a new branch for your changes. 2. If you are introducing a new api-version, create a new directory for that api-version and copy all the files from the previous version into the new directory. Make this the very first commit in your branch and then make your changes in subsequent commits. 3. Use the [linting tools](#coding-style) to check your changes for compliance with the OpenAPI v2 standard, the Azure REST API Guidelines and that Azure API Style Guide. - 4. Push to changes to the branch in your fork until the changes are ready to be integrated. + 4. Push the changes to the branch in your fork until the branch is ready to be integrated. 5. Rebase your branch if needed to incorporate any changes to **main** and submit a pull request to the **main** branch using either the "control plane" or "data plane" PR template -- the main PR template lets you select which one. 5. Resolve any issues flagged by the [Pull Request checks](#pull-request-checks). 6. Contact the ARM API Review board or Azure API Stewardship team to request PR review. From 8aff72eb5d29625a7d417b4ccdc667093a8dd27e Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Tue, 28 Jun 2022 18:03:51 -0700 Subject: [PATCH 4/6] Regen toc for CONTRIBUTING.md --- CONTRIBUTING.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f6c3c5223664..22d606416ee6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,16 +11,14 @@ This file provides general guidance for developers that are creating or updating +- [Reporting problems](#reporting-problems) +- [Avoid Breaking Changes](#avoid-breaking-changes) - [Design Guidelines](#design-guidelines) + * [Exceptions for consistency within a service](#exceptions-for-consistency-within-a-service) - [Coding Style](#coding-style) - [Directory Structure](#directory-structure) - [Pull Requests](#pull-requests) -- [Adding a new service](#adding-a-new-service) -- [Running tests](#running-tests) - * [Unit tests](#unit-tests) - * [Integration tests](#integration-tests) -- [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11) -- [Additional Resources](#additional-resources) +- [Pull Request checks](#pull-request-checks) From f2da3a27cedc2e267041f18480a1fc6d66b98e40 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Mon, 11 Jul 2022 09:16:59 -0700 Subject: [PATCH 5/6] Address PR review comments --- CONTRIBUTING.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 22d606416ee6..f04f6d06d97b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,7 +47,7 @@ Because the first rule is to avoid breaking changes and because we want APIs to ## Coding Style -REST APIs for Azure should be defined using the [OpenAPI v2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) format. +REST APIs for Azure should be defined using the [OpenAPI v2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) or [Cadl](https://aka.ms/cadl/rpaas-start)format. The REST API should also adhere to the conventions documented in the [Azure API Style Guide](https://github.com/Azure/azure-api-style-guide/blob/main/openapi-style-guide.md). @@ -68,6 +68,8 @@ If you want to contribute to the repository, follow these steps: 5. Resolve any issues flagged by the [Pull Request checks](#pull-request-checks). 6. Contact the ARM API Review board or Azure API Stewardship team to request PR review. +Microsoft employees can try out the experience at [OpenAPI Hub](https://aka.ms/openapihub) for [adding a new API version using OpenAPI Hub](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/208/OpenAPI-Hub-Adding-new-API-version). + ## Pull Request checks Every PR in this repo will go through a series of PR checks, including: @@ -87,3 +89,4 @@ Every PR in this repo will go through a series of PR checks, including: - SDK Breaking Change - When any of these PR checks fails it will post a comment to the PR with links to information on how to resolve the problem. +There is also the [CI Fix Guide](https://aka.ms/ci-fix) that describes how to fix common PR check failures. From 3ca96bb263273d7f21c0c423463a6f3cb81e7282 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Fri, 22 Jul 2022 15:44:21 -0700 Subject: [PATCH 6/6] Address PR review comments --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f04f6d06d97b..1243191899cc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,7 +75,7 @@ Microsoft employees can try out the experience at [OpenAPI Hub](https://aka.ms/o Every PR in this repo will go through a series of PR checks, including: - Breaking Changes - checks for incompatible changes in an existing api-version -- Cross Version Breaking Changes - checks for changes in a new api-version that are incompatible with prior versions +- Breaking Changes (Cross-Version) - checks for changes in a new api-version that are incompatible with prior versions - LintDiff - checks the new or changed portions of the API for compliance with the Azure REST API Guidelines and API Style Guide - Avocado - checks that new or changed files comply with the directory structure convention for this repo. - Model Validation -