Update docs to explain how the SDK namespaces are used

[ladonnaq]

Requirement: Service partners want to understand how the SDK namespaces are utilized in the release process. They are unsure if there are todos for them or if the SDK team is handling. If SDK team is handling, they still want to understand where these namespaces are utilized in the release process.

Email exchange in progress with Jesse, Laurent, Renhe, Ray, Mayuri, Allen Z, and Mariana.

[maririos]

Moving request to this issue:

• @jsquire or someone form the .NET team needs to provide a link to their docs where the information about adding a new namespace prefix is.

• @lirenhe Is helping us understand where we can find docs about how/where to use an approved package namespace:

  • Management plane
  • Data plane

[maririos]

from @lirenhe : For mgmt. SDK, more details could be found in files under azure-rest-api-specs/documentation/code-gen at main · Azure/azure-rest-api-specs (github.com) e.g. [azure-rest-api-specs/documentation/code-gen/configure-go-sdk.md at main · Azure/azure-rest-api-specs (github.com)]

The description for DPG related configuration is out of date which need to be updated. [azure-rest-api-specs/documentation/onboard-dpg-in-sdkautomation at main · Azure/azure-rest-api-specs (github.com)]

[maririos]

@lirenhe :

• Management plane: I see that not all languages have a document with the instructions. Is this something that is going to be improved during Dt?
• Data plane: Who is in charge of updating that doc? and do you have an ETA?

[lirenhe]

@lirenhe :

• Management plane: I see that not all languages have a document with the instructions. Is this something that is going to be improved during Dt?
• Data plane: Who is in charge of updating that doc? and do you have an ETA?

We have the task in Dt for documentation update, I will create separate issues and assign the owners.

[lirenhe]

For the missing Java and .NET part in mgmt. SDK, probably this is by design.

@weidongxu-microsoft @live1206, please help to confirm. thanks

[weidongxu-microsoft]

namespace is included in SDK review process https://azure.github.io/azure-sdk/policies_reviewprocess.html

This purely informational/educational session is to let the Azure SDK Architecture board get up to speed with the service and the library/new features that are coming. This allows for early feedback and will potentially affect the service design. High level topics such as API namespaces, function names, and types will be suggested in this first discussion.

for mgmt, that usually be an async review (only review the namespace).

[live1206]

https://eng.ms/docs/products/azure-developer-experience/develop/namespace-review is about the SDK namespace review guide for both management-plane and data-plane.

[maririos]

Thank you @weidongxu-microsoft and @live1206 . What our users have been wondering, is once their namespace is approved, where should they go and update it. Renhe was sharing how currently they need to do it in the Readme.md files, so I am looking for the documentation that says that and that will be applied for all the languages

[weidongxu-microsoft]

For Java, the current process is that SDK dev must manually check the namespace review issue and confirm it been approved. There is no way to retract a released Java package, hence the manual verify step.

Will update in the documentation task.

We'd hope that the namespace review issue would be integrated to the release request (or self-serve) that has this verification built-in.

[maririos]

We'd hope that the namespace review issue would be integrated to the release request (or self-serve) that has this verification built-in.

This is great. But how do users know where the namespace should go?

For example, looking at the Python documentation, I see that in the python.readme.yml file, there is a property namespace and package-name . Should both be updated? is this also applicable for the other languages?

For example, I don't see it in Go, .NET, Java

[weidongxu-microsoft]

Currently Java is in SDK repo (automation tool would update the file when Java create the 1st PR for the service) https://github.com/Azure/azure-sdk-for-java/blob/main/eng/mgmt/automation/api-specs.yaml This is Java Mgmt only. Service dev does not need to where namespace goes, it would be updated during 1st PR of the service.

(it has less rows than the full spec, because it only register the case that namespace is not same as folder name in spec -- e.g. it would ignore the row "folder cognitiveservices to namespace com.azure.resourcemanager.cognitiveservices")

[weidongxu-microsoft]

PR to update onboard doc https://github.com/Azure/azure-rest-api-specs/pull/28740

For data-plane, only provide doc for typespec. For management-plane, usually nothing need to be done for Java (besides release request with correct info).