search

Azure / azure-sdk-tools

Tools repository leveraged by the Azure SDK team.
MIT License
112 stars 172 forks source link

API Docs Preview step failing #8577

Closed scorpion-ajay closed 1 month ago

scorpion-ajay commented 1 month ago

API Docs Preview step failing, also not able to make much sense from the failure logs on the pipeline.

PR: https://github.com/Azure/azure-rest-api-specs/pull/29673

Failure in pipeline causing blocker for SDK release, please help.

image

kurtzeborn commented 1 month ago

We think this may be related (or a duplicate of) this issue: https://github.com/Azure/azure-sdk-tools/issues/8468

I've assigned both to you Jim since Daniel is out.

nickwalkmsft commented 1 month ago

Hi, I'm from the Learn ref docs team.

Our normal intake for these issues is via SitHelp, see here.

Don't worry about it for this one, I will forward this to our dev team and get back to you here.

nickwalkmsft commented 1 month ago

The error here isn't the fault of the contents of the PR, it's a problem with the ApiDocPreview build script.

ApiDocPreview uses utils.getChangedSwaggerFilesInPR to determine which of the files in the PR are Swaggers so it can submit them for the docs build, but the filtering that method does is insufficient and it sometimes includes files it shouldn't. In this case, the offending file is sdk-suppressions.yaml - you can see here in the log that it's been included as a "Swagger" (and in the lines right above that you can see where it's tried to parse the API version from the filename and fails, but it remains the list of "Swaggers" to send to the docs build anyway). When the docs build tries to parse that file as a Swagger spec it fails.

Towards finding a pattern so the filter can be fixed: sdk-suppressions.yaml appears to be a well-known filename, there's a doc about it here, but I know we saw this same problem recently in another PR (IcM here) with a file named suppressions.yaml (No sdk- prefix).

Re: #8468: the use of the legacy mapping.json build configuration instead of the current reference.config.yml configuration is not the cause of the problem here. Even if you were using reference.config.yml, you'd presumably still be using the same functions within ApiDocPreview to do the same filtering and selection of Swagger specs to submit them for the build.

wangyuantao commented 1 month ago

https://portal.microsofticm.com/imp/v3/incidents/details/526124359/home

failed on API doc preview block us on security doc fix. See the IcM above. Please prioritize the tool fix. Thanks!

nickwalkmsft commented 1 month ago

https://portal.microsofticm.com/imp/v3/incidents/details/526124359/home

failed on API doc preview block us on security doc fix. See the IcM above. Please prioritize the tool fix. Thanks!

I think this one's actually a slightly different situation - it looks there's both a yaml and a json version of the same Swagger being committed? Both of those are getting sent to the docs build as new swaggers, and the build takes both formats, so every definition is duplicated and you're getting error that usually shows up for that scenario.

I'm not sure what to say about this one, this doesn't appear to be a standard practice in this repo.

Live docs publishing for this OpenAI service doesn't have this problem because it's only configured to read the json versions.

mikeharder commented 1 month ago

Fix is to add suppressions.yaml and sdk-suppressions.yaml to deny-list here:

https://devdiv.visualstudio.com/DevDiv/_git/openapi-alps?path=/public/rest-api-specs-scripts/src/utils.ts&version=GBmain&line=656&lineEnd=657&lineStartColumn=1&lineEndColumn=1&lineStyle=plain&_a=contents

Repro:

https://github.com/Azure/azure-rest-api-specs/pull/30009

mikeharder commented 1 month ago

Fixed in prod:

https://dev.azure.com/devdiv/DevDiv/_git/openapi-alps/pullrequest/568103 https://devdiv.visualstudio.com/DevDiv/_build/results?buildId=9960576&view=results