Add CONTRIBUTING.md #19257

mikekistler · 2022-05-27T20:42:17Z

This PR adds a basic CONTRIBUTING.md file to the repo.

It covers many of the standard topics such as reporting a problem, coding style, and opening a PR.

I'm sure there is more we could add but I think it is important to get something in place quickly to provide basic guidance to service teams.

openapi-workflow-bot · 2022-05-27T20:42:19Z

Hi, @mikekistler Thanks for your PR. I am workflow bot for review process. Here are some small tips.

Please ensure to do self-check against checklists in first PR comment.

PR assignee is the person auto-assigned and responsible for your current PR reviewing and merging.

For specs comparison cross API versions, Use API Specs Comparison Report Generator

If there is CI failure(s), to fix CI error(s) is mandatory for PR merging; or you need to provide justification in PR comment for explanation. How to fix?

Any feedback about review process or workflow bot, pls contact swagger and tools team. vscswagger@microsoft.com

openapi-pipeline-app · 2022-05-27T20:42:21Z

Swagger Validation Report

️️✔️BreakingChange succeeded [Detail] [Expand]

There are no breaking changes.

️️✔️Breaking Change(Cross-Version) succeeded [Detail] [Expand]

There are no breaking changes.

️️✔️CredScan succeeded [Detail] [Expand]

There is no credential detected.

️️✔️LintDiff succeeded [Detail] [Expand]

Validation passes for LintDiff.

️️✔️Avocado succeeded [Detail] [Expand]

Validation passes for Avocado.

️️✔️ApiReadinessCheck succeeded [Detail] [Expand]

️️✔️ModelValidation succeeded [Detail] [Expand]

Validation passes for ModelValidation.

️️✔️SemanticValidation succeeded [Detail] [Expand]

Validation passes for SemanticValidation.

️️✔️PoliCheck succeeded [Detail] [Expand]

Validation passed for PoliCheck.

️️✔️SDK Track2 Validation succeeded [Detail] [Expand]

Validation passes for SDKTrack2Validation

️️✔️PrettierCheck succeeded [Detail] [Expand]

Validation passes for PrettierCheck.

️️✔️SpellCheck succeeded [Detail] [Expand]

Validation passes for SpellCheck.

️️✔️Lint(RPaaS) succeeded [Detail] [Expand]

Validation passes for Lint(RPaaS).

️️✔️CadlValidation succeeded [Detail] [Expand]

Validation passes for CadlValidation.

_{Posted by Swagger Pipeline | How to fix these errors?}

openapi-pipeline-app · 2022-05-27T20:42:22Z

Swagger pipeline restarted successfully, please wait for status update in this comment.

heaths

Great start, but I don't think opening a PR to main is an effective strategy for almost any team. Most do this and really shouldn't because they are technically making breaking changes if they treat main as a development branch, which many do - which is pretty common in the git world anyway (so just feels natural). We use main to mean published.

CONTRIBUTING.md

Co-authored-by: Heath Stewart <heaths@outlook.com>

weidongxu-microsoft

Ping me when we are ready to merge.

CONTRIBUTING.md

weidongxu-microsoft · 2022-06-10T11:40:22Z

CONTRIBUTING.md

+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.
+


Should we mention about npm prettier?

CONTRIBUTING.md

Co-authored-by: Weidong Xu <weidxu@microsoft.com>

josefree · 2022-07-11T13:50:30Z

CONTRIBUTING.md

+
+## 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.


wonder if we should recommend Cadl here for Cadl libraries contain rules that encourage following established patterns for Azure APIs. The document can be referred is https://github.com/Azure/cadl-azure/blob/main/docs/cadl-getting-started.md

CONTRIBUTING.md

josefree

I've proposed some updates in the previous comments.

mikekistler · 2022-07-11T16:18:25Z

Thanks for you comments @josefree! I just pushed a new commit that I think addresses all your concerns.

CONTRIBUTING.md

* update folder structure * small errors and CI check * [Language Text] Update swagger titles (#19835) * [Language Text] Update swagger titles * edits * address feedback * Review request for Microsoft.ContainerService to add version 2022-06-01 (#19848) * Adds base for updating Microsoft.ContainerService from version stable/2022-04-01 to version 2022-06-01 * Updates readme * Updates API version in new specs and examples * update readmes (#19421) * Add key management service profile of a managed cluster for version 2022-06-01 (#19529) * Add NetworkPlugin none option to 2022-06-01 (#19510) * Add NetworkPlugin none option to 2022-06-01 * improve description for none value * Fix violated rule R4041 for 2022-06-01 managedCluster swagger (#19581) * remove useless directive * fix R4041 * GA AKS support for Dedicated Host Group (#19547) * GA AKS support for Dedicated Host Group * fit some format minor issue * add newline in end of files * Defender updates (#19665) * Defender updates * sample * remove old description Co-authored-by: Bin Xia <binxi@microsoft.com> Co-authored-by: Matt Stam <mattstam@live.com> Co-authored-by: Jianping Zeng <zjpjack@users.noreply.github.com> Co-authored-by: Or Parnes <orparnes@microsoft.com> * Update resources.json (#19861) * Pattts/predictive autoscale 20221001 (#19765) * Rev Autoscale API from 2021-05-01-preview to 2022-10-01. * Fix minor swagger issue. Default should be 'false' * Fix swagger validation error * Defining a new package 2022-10 * AutoscaleSettingResource now reference allOf 'resource' which is the actual autoscaleSetting resource definition * Fix require property issue * Run prettier against autoscale_API.json * [Maps - Render & Spatial Services] add v2022-08-01 (#19520) * copy old swagger to new folders * set api version to 2022-08-01 * apply api changes Co-authored-by: Gigi Grajo <gigigrajo@microsoft.com> * update appconfiguration (#19330) * update appconfiguration * Update readme.python.md * Update readme.python.md * Update readme.python.md * Update readme.python.md * Update readme.python.md * Update readme.python.md * Update readme.python.md * [Hub Generated] Publish private branch 'main' (#19852) * Add StorageMover specification for PubliC Preview * SpellCheck fix * Update custom-words * Update specification/storagemover/resource-manager/readme.md Co-authored-by: Abhishek Krishna <abkrish@microsoft.com> Co-authored-by: Dapeng Zhang <dapzhang@microsoft.com> * Merging Dynatrace swagger in stable folder (#19862) * Committing base swagger version * Removing preview tag from stable folder api version * Changing version name in all the files * Updating readme.go and readme.md files * [CDN] Fix customDomains property type in Endpoint (#19788) * [CDN] Fix customDomains property type in Endpoint * Fix linter error Co-authored-by: Bo Zhang <bzhan@microsoft.com> * Adding Microsoft.Sql AdvancedThreatProtectionSettings APIs for MI on v5 tag for 2022-02-01-preview (#19866) * update folders * [Hub Generated] Review request for Microsoft.KeyVault to add version stable/7.3 (#19844) * Update description of exportable attribute and release_policy.data * Remove submodule azure-reset-api-specs * Fix description for exportable Co-authored-by: Sunny Solanki <Sunny.Solanki@microsoft.com> * Add latest StorageMover updates (#19876) * Add StorageMover specification for PubliC Preview * SpellCheck fix * Update custom-words * Update specification/storagemover/resource-manager/readme.md * Add latest StorageMover updates Co-authored-by: Abhishek Krishna <abkrish@microsoft.com> Co-authored-by: Dapeng Zhang <dapzhang@microsoft.com> * Update readme.python.md (#19899) * Update readme.python.md * Update readme.md * Moving files from azure-rest-spec-pr to azure-rest-spec repo after api review (#19878) * Moving files from azure-rest-spec-pr to azure-rest-spec repo after api review * Add known words * Removed static IP allocation only from examples (#19858) * Removed static IP allocation * Removed static only from examples Co-authored-by: Arpit Gagneja <argagnej@microsoft.com> * Update securityinsights readme.python (#19903) * update securityinsights readme.python * Update readme.python.md Co-authored-by: Zhenbiao Wei (WICRESOFT NORTH AMERICA LTD) <v-zhenbwei@microsoft.com> * fix lint errors in Synapse trigger.json (#19660) * put json files into RP folders * update readme * Add CONTRIBUTING.md (#19257) * Add CONTRIBUTING.md * Apply suggestions from PR review Co-authored-by: Heath Stewart <heaths@outlook.com> * Apply suggestions from PR review Co-authored-by: Weidong Xu <weidxu@microsoft.com> * Regen toc for CONTRIBUTING.md * Address PR review comments * Address PR review comments Co-authored-by: Heath Stewart <heaths@outlook.com> Co-authored-by: Weidong Xu <weidxu@microsoft.com> * fix devcenter readme.go.md config (#19906) * fix readme.go.md config * rename to SkuInfo * add annotation for labservices (#19884) * add to description of OS state (#19764) * [Hub Generated] Review request for Microsoft.KeyVault to add version preview/2021-06-01-preview (#19767) * Updated the managed hsm resource manager spec to include two additional properties for private endpoint connection item * Update managed hsm private endpoint connection item in mhsm spec for latest api version * Address LRO_RESPONSE_HEADER violation for managed hsm Long running operations that are annotated with x-ms-long-running-operation:true must return location header or azure-AsyncOperation in response. Added the missing location header for managed hsm update command as well as to the corresponding examples. * [Microsoft.DeviceUpdate] Adding first stable API version (#19846) * Copied the most recent preview version into the first stable version * Updated api version in new stable version, added the tag to readme.md * Fixed typo * Fixed the wrong path in readme.md * Reverted VS Code automatic breaking change * Fix broken link (#19688) * add aadObjectId property to kustoPool (#19856) Co-authored-by: Amit Elran <amelran@microsoft.com> * Updata securityinsights readme.python (#19917) * update securityinsights readme.python * update readme.python Co-authored-by: Zhenbiao Wei (WICRESOFT NORTH AMERICA LTD) <v-zhenbwei@microsoft.com> * modify readme.typescripy.md for compute package (#19607) Co-authored-by: ZiWei Chen (WICRESOFT NORTH AMERICA LTD) <v-ziweichen@microsoft.com> * Dev gubalasu frontdoor microsoft.network 2021 06 01 (#19578) * Adds base for updating Microsoft.Network from version stable/2020-05-01 to version 2021-06-01 * Updates readme * Updates API version in new specs and examples * update waf configs and examples from 2020-11-01 * Update api version in new specs and examples * Migration api update * Update readme * Fix readme * update readme * Fix readme again * Fix readme * Fix readme * update waf policy provisioning state * Update securityinsights readme.python (#19923) * update securityinsights readme.python * update readme.python * last modify * Update readme.python.md Co-authored-by: Zhenbiao Wei (WICRESOFT NORTH AMERICA LTD) <v-zhenbwei@microsoft.com> * sync with changes made to master * update folder structure * small errors and CI check * update folders * put json files into RP folders * update readme * resolve capitalization and number misplacement accident Co-authored-by: Theodore Chang <theodore.l.chang@gmail.com> Co-authored-by: Deyaaeldeen Almahallawi <dealmaha@microsoft.com> Co-authored-by: FumingZhang <81607949+FumingZhang@users.noreply.github.com> Co-authored-by: Bin Xia <binxi@microsoft.com> Co-authored-by: Matt Stam <mattstam@live.com> Co-authored-by: Jianping Zeng <zjpjack@users.noreply.github.com> Co-authored-by: Or Parnes <orparnes@microsoft.com> Co-authored-by: Alexander Batishchev <abatishchev@gmail.com> Co-authored-by: PatrickTseng <pattts@microsoft.com> Co-authored-by: gigi <52640944+gigigoo0@users.noreply.github.com> Co-authored-by: Gigi Grajo <gigigrajo@microsoft.com> Co-authored-by: zhenbiao wei <424401670@qq.com> Co-authored-by: Abhishek Krishna <AbhishekKrishna123@users.noreply.github.com> Co-authored-by: Abhishek Krishna <abkrish@microsoft.com> Co-authored-by: Dapeng Zhang <dapzhang@microsoft.com> Co-authored-by: Divyansh Agarwal <83802474+divyansh3131@users.noreply.github.com> Co-authored-by: t-bzhan <61817681+t-bzhan@users.noreply.github.com> Co-authored-by: Bo Zhang <bzhan@microsoft.com> Co-authored-by: Uriel Cohen <urielc@microsoft.com> Co-authored-by: susolank <73919400+susolank@users.noreply.github.com> Co-authored-by: Sunny Solanki <Sunny.Solanki@microsoft.com> Co-authored-by: Ralf Beckers <bexxx@users.noreply.github.com> Co-authored-by: arpit-gagneja <gagneja.arpit@gmail.com> Co-authored-by: Arpit Gagneja <argagnej@microsoft.com> Co-authored-by: Zhenbiao Wei (WICRESOFT NORTH AMERICA LTD) <v-zhenbwei@microsoft.com> Co-authored-by: YanjunGao <85206987+yanjungao718@users.noreply.github.com> Co-authored-by: Mike Kistler <mikekistler@microsoft.com> Co-authored-by: Heath Stewart <heaths@outlook.com> Co-authored-by: Weidong Xu <weidxu@microsoft.com> Co-authored-by: Jiahui Peng <46921893+Alancere@users.noreply.github.com> Co-authored-by: j-zhong-ms <107880703+j-zhong-ms@users.noreply.github.com> Co-authored-by: Tom FitzMacken <tomfitz@microsoft.com> Co-authored-by: neeerajaakula <81248992+neeerajaakula@users.noreply.github.com> Co-authored-by: darkoa-msft <61987922+darkoa-msft@users.noreply.github.com> Co-authored-by: Roy Wellington <53838718+roy-work@users.noreply.github.com> Co-authored-by: Amit Elran <amitelran2110@gmail.com> Co-authored-by: Amit Elran <amelran@microsoft.com> Co-authored-by: kazrael2119 <98569699+kazrael2119@users.noreply.github.com> Co-authored-by: ZiWei Chen (WICRESOFT NORTH AMERICA LTD) <v-ziweichen@microsoft.com> Co-authored-by: gubalasu <59630928+gubalasu@users.noreply.github.com>

Add CONTRIBUTING.md

af9f6a0

openapi-assignment-bot bot assigned dw511214992 May 27, 2022

mikekistler marked this pull request as draft May 27, 2022 20:42

mikekistler unassigned dw511214992 May 27, 2022

heaths requested changes May 27, 2022

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

CONTRIBUTING.md Outdated Show resolved Hide resolved

CONTRIBUTING.md Show resolved Hide resolved

CONTRIBUTING.md Outdated Show resolved Hide resolved

mikekistler commented May 31, 2022

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

Apply suggestions from PR review

061c425

Co-authored-by: Heath Stewart <heaths@outlook.com>

mikekistler requested a review from heaths May 31, 2022 13:23

heaths approved these changes May 31, 2022

View reviewed changes

mikekistler marked this pull request as ready for review June 1, 2022 02:28

openapi-assignment-bot bot assigned weidongxu-microsoft Jun 1, 2022

mikekistler requested review from markweitzel, tg-msft, josefree and akning-ms June 1, 2022 02:29

weidongxu-microsoft approved these changes Jun 10, 2022

View reviewed changes

mikekistler commented Jun 29, 2022

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

mikekistler and others added 2 commits June 28, 2022 18:01

Apply suggestions from PR review

bed0a9f

Co-authored-by: Weidong Xu <weidxu@microsoft.com>

Regen toc for CONTRIBUTING.md

8aff72e

josefree reviewed Jul 11, 2022

View reviewed changes

CONTRIBUTING.md Show resolved Hide resolved

josefree requested changes Jul 11, 2022

View reviewed changes

Address PR review comments

f2da3a2

mikekistler requested a review from josefree July 11, 2022 16:17

mikekistler commented Jul 13, 2022

View reviewed changes

CONTRIBUTING.md Outdated Show resolved Hide resolved

josefree approved these changes Jul 20, 2022

View reviewed changes

Address PR review comments

3ca96bb

heaths merged commit 226c70f into Azure:main Jul 22, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add CONTRIBUTING.md #19257

Add CONTRIBUTING.md #19257

mikekistler commented May 27, 2022

openapi-workflow-bot bot commented May 27, 2022

openapi-pipeline-app bot commented May 27, 2022 •

edited

Loading

openapi-pipeline-app bot commented May 27, 2022 •

edited

Loading

heaths left a comment

weidongxu-microsoft left a comment

weidongxu-microsoft Jun 10, 2022

josefree Jul 11, 2022

josefree left a comment

mikekistler commented Jul 11, 2022

		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.


		## 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.

Add CONTRIBUTING.md #19257

Add CONTRIBUTING.md #19257

Conversation

mikekistler commented May 27, 2022

openapi-workflow-bot bot commented May 27, 2022

openapi-pipeline-app bot commented May 27, 2022 • edited Loading

Swagger Validation Report

openapi-pipeline-app bot commented May 27, 2022 • edited Loading

heaths left a comment

Choose a reason for hiding this comment

weidongxu-microsoft left a comment

Choose a reason for hiding this comment

weidongxu-microsoft Jun 10, 2022

Choose a reason for hiding this comment

josefree Jul 11, 2022

Choose a reason for hiding this comment

josefree left a comment

Choose a reason for hiding this comment

mikekistler commented Jul 11, 2022

openapi-pipeline-app bot commented May 27, 2022 •

edited

Loading

openapi-pipeline-app bot commented May 27, 2022 •

edited

Loading