Consolidate support guidance for API spec PR tools

[konrad-jamrozik]

Currently there are many ways of users reporting to us problems with the tooling we inherited from Shanghai related to Azure REST API spec PR validation tooling. See the comment below for list of known sources of support requests to monitor. Note that we have guidance on how to handle requests coming through these sources at https://aka.ms/azsdk/support/internal.

This work item is about doing two things:

• Consolidating all the support streams. For now the idea is to funnel everybody to two places, depending on scenario: the API Spec Review or Service API Toolset channels.
• Updating all the docs to properly direct users to the 2 channels. There are many docs spread over many places to update, plus people directing users to engineers instead of channels.

Related work

• Consolidate azure-rest-api-specs PR review workflow #5865
• [ShiftLeft] Usability enhancement of API Spec Pipeline #5554
• https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/942/Doc-map

Work done so far

• Create user guidance for API spec PR tools at https://aka.ms/azsdk/support/spectools
• Create internal EngSys team guidance for API spec PR tools at https://aka.ms/azsdk/support/internal
• Consolidate aka.ms links:
  • https://aka.ms/azsdk/support/internal
  • https://aka.ms/azsdk/support/spectools
  • https://aka.ms/azsdk/support/spectools-channel
  • https://aka.ms/azsdk/support/specreview
  • https://aka.ms/azsdk/support/specreview-channel
• Write guidance for weekly triage: Consolidate API spec PR tooling issue management for weekly triage #5930

[konrad-jamrozik]

Known sources of support requests to monitor

• Emails sent to Shift Left Support shiftleftsupport@microsoft.com
• ShiftLeft support form: https://aka.ms/ShiftLeftSupportForm
• Emails sent to Swagger and Tools Team vscswagger@microsoft.com
• Emails sent:
  • From Josephine Qiu
    • AND to Ke Yu (WICRESOFT NORTH AMERICA LTD)
    • AND with CC set to Swagger and Tools Team vscswagger@microsoft.com
  • These emails have subject like e.g.: New Response to Swagger Validation Feedback: 3/12/2023 12:48:58 PM and they originate from Swagger Validation Feedback form.
• Teams messages posted to Azure SDK / Service API Toolset channel.
• Teams messages posted to Azure SDK / API Spec Review channel.

Known support guidance that needs consolidating

• Any guidance that is provided in the Known sources of support requests to monitor listed above.
• The new, official guidance we added in March 2023: https://aka.ms/azsdk/support/spectools
  • This is the new, proper source of truth for support guidance; everything else should be adjusted/consolidated to match it.
• https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/534/Engage-with-the-Azure-SDK-team
  • This link is being shared by Josephine Qiu and mentioned in the ShiftLeft onboarding docs/workflow/form. Folks are directed there with notification the onboarding was suspended.
    • Mentioned here: https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/606/Enable-API-Spec-Pipeline
    • Mentioned here: https://aka.ms/ShiftLeftSupportForm
• Various spec PR guidance, as enumerated in Consolidate azure-rest-api-specs PR review workflow #5865
• The docs and links in the automated comments made on PRs to specs repo by our tooling. For example, see the comments on Refactor cache swagger to deduplicate SkuName enum definitions. azure-rest-api-specs#23049
  • For example, this comment says If any further question about AME onboarding or validation tools, please view the [FAQ](https://aka.ms/faqinprreview). where the FAQ points to https://github.com/Azure/azure-rest-api-specs/wiki/FAQ-in-Swagger-PR-Review.
  • The following alias is also mentioned: vscswagger@microsoft.com, in this example openapi-owkrflow-bot comment. See https://aka.ms/azsdk/support/internal for context on it.
• Need to look through https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki in general to find any other outdated guidance.
  • For example, on 4/5/2023 I linked to spectools shortlink on ShiftLeft workflow page.
  • Updates needed here: https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/909/API-spec-PR-review?anchor=management-plane-api-review
• Need to look through the repo README: https://github.com/Azure/azure-rest-api-specs
• Guidance inside Release Planner (owned by LaDonna Q). 4/3/2023:

  So within the release planner we currently have steps to enable the API Spec pipeline, complete API scenario test, etc.
  We were encouraging management plane teams to adopt the process and use the pipeline.
  I did not have it has a requirement in the launch criteria.  It was a "best practice" and "strongly suggested" for new services.  
  TypeSpec (Cadl) wanted teams to do it

• Swagger Validation Feedback form is given in HealthBot S360 messages, which most likely originate from Swagger KPI, which most likely gets data from Live Validation. Example HealthBot message.
• logError('Fatal Error ${JSON.stringify(e)}. Please report to adxsr@microsoft.com'); in https://github.com/Azure/azure-rest-api-specs-pipeline/blob/master/scripts/utils.ts#L121
• This links in the table to ShiftLeft onboarding guidance, which is suspended: https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/539/Onboarding-Scenarios
• Links in ShiftLeft comments like this one: https://github.com/Azure/azure-rest-api-specs-pr/pull/12059#issuecomment-1506333911
  • Among others, it links to a wiki page that is under deprecated folder.
• Consolidate https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/771/CI-check-fix-guide into https://aka.ms/ci-fix
• Any comments generated on PRs by our automation, e.g. this PR comment, which is a control plane PR template, among many other things, links to this FAQ which uses https://aka.ms/StartWithOpenAPISpecs and https://aka.ms/ContributeToSwagger.
• here: If you encounter any issue(s), please open issue(s) at https://github.com/Azure/azure-openapi-validator/issues .

[konrad-jamrozik]

Closing as not planned: we did a major documentation migration push here:

• [Documentation] Migrate spec PR review workflow support docs to EngHub #6618

It is not complete; for example, a lot of the things mentioned in this comment above are not migrated:

• Consolidate support guidance for API spec PR tools #5867 (comment)

On the other hand, a lot of the items from the comments were taken care of as part of the #6618 migration.

But it is good enough, for now.