New API Readiness UI: Improve TypeSpec Onboarding experience

[ladonnaq]

The API Readiness App has gaps related to Cadl onboarding. Let's use this epic to discuss and track the changes needed in the new UI and supporting documentation to address these gaps.

Getting started

• [ ] Complete Cadl installation - provide links to the specific documents they need to install Cadl and get their environment setup

• [ ] New user's to Cadl should complete the Cadl tutorial first - https://azure.github.io/cadl-azure/

• [ ] Review the Guidelines - https://aka.ms/azapi/guidelines, https://aka.ms/azapi/style, https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#api-versioning, https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md, https://aka.ms/aprwiki,

• Describe your API using Cadl

• [ ] Service partners who have already described their API using Open API are requesting that their existing API version be converted to a base Cadl that they can update vs starting from scratch. We need to provide a way from them to request that Azure SDK engineeing team does this for them. (since our team does not want to make the tool available for service partner's to use).

• [ ] Provide links to Azure Cadl documentation and templates

• Cadl Azure Docs: aka.ms/cadl/azuredoc

• Cadl Azure Playground: aka.ms/trycadlazure

• Cadl Azure Process Docs: aka.ms/cadl/start

• Cadl Discussion Teams channel: aka.ms/cadl/discussions

Prepare for API Review

• [ ] Draft Hero/Champion scenarios - link & Examples
• [ ] Create Core Concepts document - https://github.com/Azure/azure-sdk-pr/blob/main/onboarding/Core_Concepts.pdf

TypeSpec Validation and API Readiness - TypeSpec + DPG User flow

• [ ] Associate the pull request (PR) for the TypeSpec & API Version that is related to the SDK release plan.
• [ ] Review TypeSpec validation and clean up any errors.
• [ ] If previous API version exist, then SDK breaking change review and approval for any breaking changes. For data plane, this is arch board activity currently and it is done during the SDK review. However, the SDK breaking change review board does the review at the same time that the ARM Review board reviews the new management plane (ARM) API version. We should consider moving the SDK breaking change review earlier in the process for data plane SDKs that are generated code.
• [ ] Schedule APIReview with the API Stewardship Board
• [ ] Review and improve the quality of the generated API Reference Document
• [ ] API Stewardship Board approval for the API version

[live1206]

@ladonnaq Could you clarify more about where to add the information and steps in which App?

In the data-plane API Readiness App, there is a step named Design and Define Your Service APIs, it only contains a wiki page how to get started with Cadl for Azure Data Plane Services:

[ladonnaq]

@ladonnaq Could you clarify more about where to add the information and steps in which App?

In the data-plane API Readiness App, there is a step named Design and Define Your Service APIs, it only contains a wiki page how to get started with Cadl for Azure Data Plane Services:

Hello @live1206 - I think until Crystal provides the new UI we could have 3 screens that are logical steps in the flow.

Getting started

• [ ] Complete Cadl installation - provide links to the specific documents they need to install Cadl and get their environment setup

• [ ] New user's to Cadl should complete the Cadl tutorial first - https://azure.github.io/cadl-azure/

• [ ] Review the Guidelines - https://aka.ms/azapi/guidelines, https://aka.ms/azapi/style, https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#api-versioning, https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md, https://aka.ms/aprwiki,

• Describe your API using Cadl

• [ ] Service partners who have already described their API using Open API are requesting that their existing API version be converted to a base Cadl that they can update vs starting from scratch. We need to provide a way from them to request that Azure SDK engineeing team does this for them. (since our team does not want to make the tool available for service partner's to use).

• [ ] Provide links to Azure Cadl documentation and templates

Prepare for API Review

• [ ] Draft Hero/Champion scenarios - link & Examples
• [ ] Create Core Concepts document - https://github.com/Azure/azure-sdk-pr/blob/main/onboarding/Core_Concepts.pdf

Would you like me to provide a "powerpoint" mockup?

[mikekistler]

Here's the set of links I give to service teams:

Cadl Azure Docs: aka.ms/cadl/azuredoc Cadl Azure Playground: aka.ms/trycadlazure Cadl Azure Process Docs: aka.ms/cadl/start Cadl Discussion Teams channel: aka.ms/cadl/discussions

Is there anything else you need from me?

[ladonnaq]

Here's the set of links I give to service teams:

Cadl Azure Docs: aka.ms/cadl/azuredoc Cadl Azure Playground: aka.ms/trycadlazure Cadl Azure Process Docs: aka.ms/cadl/start Cadl Discussion Teams channel: aka.ms/cadl/discussions

Is there anything else you need from me?

Thanks Mike! We will make sure these links are in the API readiness app. Do you know if Core Concepts is still a requirement for the API Review for Cadl + DPG?

[mikekistler]

Do you know if Core Concepts is still a requirement for the API Review for Cadl + DPG?

Yes this is still a requirement. But I'm not aware of anyplace that we define what that means. So far this has not been a problem.

[josefree]

In the data-plane API Readiness App, there is a step named Design and Define Your Service APIs, it only contains a wiki page how to get started with Cadl for Azure Data Plane Services:

LaDonna, I wonder these steps should be maintained in a wiki (Internal wiki? published via Engineering Hub?) I recalled we prefer not to make App blade filled with documentation.

[ladonnaq]

In the data-plane API Readiness App, there is a step named Design and Define Your Service APIs, it only contains a wiki page how to get started with Cadl for Azure Data Plane Services:

LaDonna, I wonder these steps should be maintained in a wiki (Internal wiki? published via Engineering Hub?) I recalled we prefer not to make App blade filled with documentation.

All of the "soft requirements" are not really suitable for the Release Planner because they are not actions we can validate. For example, completing the Cadl tutorial. I think it would be better to have one wiki page to direct the users. But it should be simple and easy to follow. We should also automate whatever is possible. For example, can we create the directory structure for them? We already should have most of that information.

[maririos]

As it is, this issue doesn't have specific asks for the Release Planner. I'm going to close it.