search

Azure / azure-sdk-tools

Tools repository leveraged by the Azure SDK team.
MIT License
114 stars 180 forks source link

Identify API Spec Type and API version via Release Planner/API readiness and restrict SDK types to specific release plan types #8291

Closed ladonnaq closed 5 months ago

ladonnaq commented 6 months ago

Requirement: The SDK codegen teams (Management and Data) need to know if the API Specs is preview vs stable and the API version that will be covered in the SDK version. There is no straight forward to obtain this information programmatically. In the near term, we can ask the user to provide this information.

Questions: 

### Draft of Tasks
- [ ] Draft of UI changes.  (La Donna)
- [ ] Private preview release plans do include SDK releases.   Update the "Create a release plan" feature to ask user the "API Spec Type" with options of "preview" or "stable".  
- [ ] GA release plan should only be for stable SDKs.  Modify the "Create a release plan" feature to only allow stable SDKs for GA release plans. 
- [ ] Public Preview release plans should only be for Beta SDKs.  Modify the "Create a release plan" feature to only allow Beta SDKs for Public Preview release plans. 
- [ ]  Beta SDKs can be created from preview or stable API version.  Update the "Create a release plan" feature to ask user the "API Spec Type" with options of "preview" or "stable".  
- [ ]  Stable SDKs required stable API version.   Update the "Create a release plan" feature to allow the user to confirm that the "API Spec Type" is "stable".  
- [ ] In the API readiness App (existing UI) updates for all release plan types.  Add "API details" to the "Assoicate Pull Request" step.  Include the API Spec Type selected during creation of the release plan.  Add a new field that request user to provide the API version.
maririos commented 6 months ago

Do we allow the user to change the API Spec type? If we do, it could change the release plan type (based on tasks suggested below). @maririos - I don't think we should allow users to change API Spec type, SDK to be released type, and release plan type. If any of these values need to change, they would need to create a new release plan. What do you think?

Agree

I have API Spec PRs that include changes to multiple API versions. Is this a scenario that we need to support?

No. Neither Spec review board (arm or data) allow this. Our tooling will also get confused. People need to make individual PRs for indivitual API versions

ladonnaq commented 6 months ago

Do we allow the user to change the API Spec type? If we do, it could change the release plan type (based on tasks suggested below). @maririos - I don't think we should allow users to change API Spec type, SDK to be released type, and release plan type. If any of these values need to change, they would need to create a new release plan. What do you think?

Agree

I have API Spec PRs that include changes to multiple API versions. Is this a scenario that we need to support?

No. Neither Spec review board (arm or data) allow this. Our tooling will also get confused. People need to make individual PRs for indivitual API versions

Thanks, then we do not worry about this scenario. :-)

maririos commented 6 months ago

@ladonnaq currently the release planner type is tied to the API spec type. So here are clarifying questions:

Private preview release plans do include SDK releases. Update the "Create a release plan" feature to ask user the "API Spec Type" with options of "preview" or "stable".

Nothing to do here. There are no SDKs and the user already selected the API spec type as private

GA release plan should only be for stable SDKs. Modify the "Create a release plan" feature to only allow stable SDKs for GA release plans.

I disagree. There are scenarios where the API spec is GA but the SDK is beta version. and this should be allowed. For GA release plans, we don't need to make any changes

Add a new field that request user to provide the API version.

That will need to happen in a separate work item as the work there is way more involved

ladonnaq commented 6 months ago

@ladonnaq currently the release planner type is tied to the API spec type. So here are clarifying questions:

Private preview release plans do include SDK releases. Update the "Create a release plan" feature to ask user the "API Spec Type" with options of "preview" or "stable".

Nothing to do here. There are no SDKs and the user already selected the API spec type as private

GA release plan should only be for stable SDKs. Modify the "Create a release plan" feature to only allow stable SDKs for GA release plans.

I disagree. There are scenarios where the API spec is GA but the SDK is beta version. and this should be allowed. For GA release plans, we don't need to make any changes

Add a new field that request user to provide the API version.

That will need to happen in a separate work item as the work there is way more involved

Private Preview- I agree with your comment. GA - The scenario you mentioned is covered in the Public Preview release plan. - " scenarios where the API spec is GA (stable) but the SDK is beta version". The GA release plan should only target Stable SDKs. Our APEX requirements align Public Preview with Beta SDKs and GA with Stable SDKs. However, if this approach does not make sense for non-APEX, then we can go with what you recommend. Let me know if you want to discuss. API Version - I agree and will create a new issue.

maririos commented 6 months ago

@ladonnaq : you can test this now in DEV instance. I also made a video. What do you think?

https://github.com/Azure/azure-sdk-tools/assets/9868623/ce9ffe03-0e12-49d4-b29f-bad85b0293cb

ladonnaq commented 6 months ago

Thanks, love the video! I will test tomorrow.

ladonnaq commented 5 months ago

@maririos - I have confirmed in PPE that Public Preview release plans only allow Beta SDKs. I have also confirmed that GA release plans allow Beta and Stable. As I mentioned earlier, I disagree with this design because from an APEX perspective GA aligns to stable APIs and stable SDKs. Stable SDKs can be used to generate Beta SDKs using the Public Preview release plan because Public Preview aligns with Beta SDKs. I think it makes more sense to align the release plans to the SDK type (beta or stable). I will reach out to our stakeholders to discuss and provide update in the GitHub issue.
FYI - There is also another approach we could take, which I believe is needed based on feedback from service partners working on non-APEX release scenarios. The release plan terms we use now (Private Preview, Public Preview, and GA) are because the MVP Release Planner scope was APEX release scenarios. We added support for non-APEX, which was not on our MVP roadmap, to assist in accelerating TypeSpec adoption. We could move away from using these terms to identify release plan types since they are APEX centric terms. Instead, the release plan types could be: API Spec (no SDKs released), Beta SDKs, Stable SDKs. Then we could allow user to confirm release plan is for APEX and identify the lifecycle, which is needed so that the S360/CLC attestation can be automated. We would be able to identify all release scenarios that relate to API Spec, Beta SDKs, Stable SDKs during the creation of the release plans and then next semester customize based on the release scenario.

maririos commented 5 months ago

We could move away from using these terms to identify release plan types since they are APEX centric terms. Instead, the release plan types could be: API Spec (no SDKs released), Beta SDKs, Stable SDKs

Oh I love this actually!! Could you create a separate issue and we look into the implications of this?

maririos commented 5 months ago

As for the requirements of this issue, this has been complited