Gaps new services/initial beta Public Preview and timing of publishing API Spec (private repo to public repo)

ladonnaq commented 1 year ago

This scenario applies to both management and data plane, in particular for new services. This is a blocking issue that we need to resolve as it blocks onboarding service teams to the release planner.

Scenario

The service team is working on Private Preview or limited Public Preview, their spec pull request is into RPSaaSMaster branch (management plane RPaaS services) or the main (data plane and non-RPaaS management plane) of the private spec repo. For private preview the will complete API Readiness only, no SDKs released.
When the service moves on to Public Preview or GA, they should initiate another spec pull request to merge into main branch of the public spec repo. The specs could be exactly the same as previously created private preview version, but the version label should be with later date. Refer to https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#api-versioning.
In the release planner, they should create a new release plan with target phase to be Public Preview or GA. Then the release plan will include SDK release. In the API Readiness app, they could initially associate a spec pull request in the private repo. However, before SDK release, they must publish this API Spec to the public repo. However, many new services do not publish their API Spec until announcement (because they are under embargo, do not want sensitive information in public repo, etc). If we force them to publish the API Spec before they can continue to SDK release, then they are not going to have time to complete the work they need to do to prepare for the SDK release.

Suggested solution:

Give the option to "Push to Public" at the end of API Readiness but allow option to continue to SDK release app without publishing the API Spec to public. We need to explain very clearly what publishing the API Spec to public means. A service team engineer was testing the release planner and published their API Spec before they were ready to do so because he did not understand fully what the button meant. When the Push to Public button is selected it will generate another API Spec pull request in the main branch of the public specs repo. This PR should then be the PR that is associated with the release plan.
There needs to be an option to "Push to Public" in the SDK Release app vs routing teams back to the API Readiness app. Perhaps we should show the PR for API readiness and let them know they need to publish it before the SDKs can be released.
For SDK release today the most current PR in the public repo is requested by OpenAPI Hub when teams request SDK release. This PR may not meet the API Readiness check because it could be a change to something that does not trigger the full review process in the PR. For example, update to readme. Since we have already confirmed API readiness, we may want to consider not trying to validate this PR. Maybe we look to see if it merged and it is continue. @maririos If there is a failure or errors in the PR, will it still merge?

maririos commented 1 year ago

@maririos If there is a failure or errors in the PR, will it still merge?

I know there is a way to overwrite the restriction so the PR can be merged. This is something that is managed by the Reviewer of the PR

maririos commented 1 year ago

Revisit when we look into the SDK Release apps

maririos commented 1 year ago

This is a big issue so I am going to open individuals for it and eventually close this.

Give the option to "Push to Public" at the end of API Readiness but allow option to continue to SDK release app without publishing the API Spec to public. We need to explain very clearly what publishing the API Spec to public means.

https://github.com/Azure/azure-sdk-tools/issues/6470

There needs to be an option to "Push to Public" in the SDK Release app vs routing teams back to the API Readiness app. Perhaps we should show the PR for API readiness and let them know they need to publish it before the SDKs can be released.

Covered by https://github.com/Azure/azure-sdk-tools/issues/5859

Questions for @ladonnaq :

"This PR should then be the PR that is associated with the release plan" You mean we change the PR associated? will that involve for the user to do the API Readiness process again?

maririos commented 1 year ago

This has been covered by design https://www.figma.com/file/JzbPB3xPwrjdxJ5SiG7hYD/Design-sync%3A-SDK-readiness?type=whiteboard&node-id=0-1&t=1lCBRP1NpVo69ZVV-0

Azure / azure-sdk-tools

Gaps new services/initial beta Public Preview and timing of publishing API Spec (private repo to public repo) #6068