-
Notifications
You must be signed in to change notification settings - Fork 5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve message for the NewApiVersionRequired label #24058
Conversation
Hi, @konrad-jamrozik Thanks for your PR. I am workflow bot for review process. Here are some small tips. Any feedback about review process or workflow bot, pls contact swagger and tools team. vscswagger@microsoft.com |
Swagger Validation Report
|
Swagger pipeline restarted successfully, please wait for status update in this comment. |
Swagger pipeline started successfully. If there is ApiView generated, it will be updated in this comment. |
@@ -39,7 +39,7 @@ | |||
- rule: | |||
type: label | |||
label: NewApiVersionRequired | |||
onLabeledComments: "<b>NewApiVersionRequired reason:</b></br> </br><b>A service’s API is a contract with customers and is represented by using the api-version query parameter. Changes such as adding an optional property to a request/response or introducing a new operation is a change to the service’s contract and therefore requires a new api-version value. This is critically important for documentation, client libraries, and customer support. </b> </br></br> EXAMPLE: if a customer calls a service in the public cloud using <b>api-version=2020-07-27</b>, the new property or operation may exist but if they call the service in a government cloud, air-gapped cloud, or Azure Stack Hub cloud using the same api-version, the property or operation may not exist. Because there is no clear relationship between the service api-version and the new property/operation, customers can’t trust the documentation and Azure customer have difficulty helping customers diagnose issues. In addition, each client library version documents the service version it supports. When an optional property or new operation is added to a service and its Swagger, new client libraries must be produced to expose this functionality to customers. Without updating the api-version, it is unclear to customers which version of a client library supports these new features. " | |||
onLabeledComments: "The automation detected this Pull Request introduces breaking changes to an existing API version and hence it added the <code>NewApiVersionRequired</code> label. This means you cannot proceed with merging this PR until you complete one of the following action items:<br/><br/>- A) Submit a new PR instead of this one, or modify this PR, so that it introduces a new API version instead of introducing breaking changes to an existing API version. The automation will remove the label once it detects there are no more breaking changes.<br/>- B) OR you can request an approval of the breaking changes, get it reviewed, and approved. The reviewer will add <code>Approved-BreakingChange</code> label if they approve.<br/><br/>For additional guidance, please see https://aka.ms/NewApiVersionRequired<br/> " |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
FYI I moved the removed explanation to https://aka.ms/NewApiVersionRequired
This is a PR made by the Azure SDK Engineering System team.
This PR improves the comment added when
NewApiVersionRequired
label is added. An example occurrence of the modified comment.This PR contributes to: