Board Review: Management Plane Namespace Review Azure.ResourceManager.Migrate

[srilipta-swain]

Thank you for submitting this review request. Thorough review of your management library namespaces ensures that your library names are consistent with the guidelines and the consumers of your management library have a consistently good experience when using Azure.

To ensure consistency, all language library names will generally be reviewed together.

Before submitting, ensure you adjust the title of the issue appropriately.

Note that the required material must be included before a meeting can be scheduled.

Contacts and Timeline

• Responsible service team: Azure Migrate engineering team
• Main contacts: srswain, sunising
• Expected code complete date: 15-09-24
• Expected release date: 20-10-24

About the Service (required)

• Link to documentation introducing/describing the service: Azure Migrate
• Link to the service REST APIs Specs: azure-rest-api-specs/specification/migrate/resource-manager/Microsoft.Migrate at main · Azure/azure-rest-api-specs (github.com)
• Link to GitHub issue for previous review sessions, if applicable: Board Review: Management Plane Namespace Review <Azure.ResourceManager.Migrate> · Issue #6964 · Azure/azure-sdk (github.com)

Namespace Proposals (required per language)

In the examples below please replace every occurrence of [ResourceProviderName] with your the service resource provider name. Be sure to keep the casing shown with [ResourceProviderName] when replacing it with the service resource provider name.

• .NET: Azure.ResourceManager.Migration.Assessment
• Java: azure-resourcemanager-migration-assessment (com.azure.resourcemanager.migration.assessment)
• Go/Golang: sdk/resourcemanager/migrationassessment/armmigrationassessment
• JavaScript: @azure/arm-migrationassessment
• Python: azure-mgmt-migrationassessment

• .NET: Azure.ResourceManager.Migration.Modernization
• Java: azure-resourcemanager-migration-modernization (com.azure.resourcemanager.migration.modernization)
• Go/Golang: sdk/resourcemanager/migrationmodernization/armmigrationmodernization
• JavaScript: @azure/arm-migrationmodernization
• Python: azure-mgmt-migrationmodernization

• .NET: Azure.ResourceManager.Migration.Hub
• Java: azure-resourcemanager-migration-hub (com.azure.resourcemanager.migration.hub)
• Go/Golang: sdk/resourcemanager/migrationhub/armmigrationhub
• JavaScript: @azure/arm-migrationhub
• Python: azure-mgmt-migrationhub

Thank you!

[srilipta-swain]

To provide more context. We are from Azure Migrate service and we provide the following capabilities:-

• Discovery workloads/servers from customer's on-premise setups.
• Assess and migrate these workloads to azure.

We're a GA service and are planning to do an SDK release for management plane APIs aligning with APEX PLR requirements.

We own two RP namespaces:-

• Microsoft.OffAzure - Discovery Services
• Microsoft.Migrate - Assessment and Migrate powering services.

For Microsoft.OffAzure RP, we have got the namespace approved i.e. Azure.ResourceManager.MigrationDiscovery. Now we intend to split the Microsoft.Migrate RP which contains 3 tracked resources. Each tracked resource has multiple APIs exposed via proxy resources and these APIs are owned by different services under single namespace. We plan to publish multiple SDKs according to the swaggers published in the migrate/ folder in rest-api-spec repo.

Previously, we had a namespace approved i.e. zure.ResourceManager.Migrate (issue attached). I'd like to put a proposal for breaking up the SDK under the namespace as follows:-

• .NET: Azure.ResourceManager.MigrationAssessment
• Java: azure-resourcemanager-migrationassessment (com.azure.resourcemanager.migrationassessment)
• Go/Golang: sdk/resourcemanager/migrationassessment/armmigrationassessment
• JavaScript: @azure/arm-migrationassessment
• Python: azure-mgmt-migrationassessment

• .NET: Azure.ResourceManager.MigrationModernization
• Java: azure-resourcemanager-migrationmodernization (com.azure.resourcemanager.migrationmodernization)
• Go/Golang: sdk/resourcemanager/migrationmodernization/armmigrationmodernization
• JavaScript: @azure/arm-migrationmodernization
• Python: azure-mgmt-migrationmodernization

• .NET: Azure.ResourceManager.MigrationHub
• Java: azure-resourcemanager-migrationhub (com.azure.resourcemanager.migrationhub)
• Go/Golang: sdk/resourcemanager/migrationhub/armmigrationhub
• JavaScript: @azure/arm-migrationhub
• Python: azure-mgmt-migrationhub

We have updated the package names according to the issue template. If you have suggestions for more customized package names to improve user-friendliness, please let us know. Additionally, if separate issues need to be raised for separate namespaces, we will gladly do so.

[ArthurMa1978]

We have already discussed the pros and cons of splitting the SDK for the same RP, and we strongly advise against doing so. For your service, stable versions have already been released for Go and JS.
Splitting it now would result in a breaking change.
So I don't think we could split it.

[josefree]

Please follow this wiki to walk through breaking change process before introducing a breaking change. Let us know if you've already complete this.

[srilipta-swain]

We have already discussed the pros and cons of splitting the SDK for the same RP, and we strongly advise against doing so. For your service, stable versions have already been released for Go and JS. Splitting it now would result in a breaking change. So I don't think we could split it.

Hi @ArthurMa1978, seems like these were not released by our team. I have reached out to the concerned folks, let me get back on this.

[ArthurMa1978]

We have already discussed the pros and cons of splitting the SDK for the same RP, and we strongly advise against doing so. For your service, stable versions have already been released for Go and JS. Splitting it now would result in a breaking change. So I don't think we could split it.

Hi @ArthurMa1978, seems like these were not released by our team. I have reached out to the concerned folks, let me get back on this.

These are carried over from old track 1 SDK, and it has been GAed for over 2 years.

[ArthurMa1978]

As @josefree mentioned, please follow the wiki to walk though breaking change process first.

[srilipta-swain]

We have already discussed the pros and cons of splitting the SDK for the same RP, and we strongly advise against doing so. For your service, stable versions have already been released for Go and JS. Splitting it now would result in a breaking change. So I don't think we could split it.

Hi @ArthurMa1978, seems like these were not released by our team. I have reached out to the concerned folks, let me get back on this.

These are carried over from old track 1 SDK, and it has been GAed for over 2 years.

Hi @ArthurMa1978 , I got a chance to connect with @ladonnaq and was able to get users data for these SDKs. I will go through the breaking changes link provided by @josefree and try to follow to process to get this closed. Thanks !

[srilipta-swain]

Hi @ArthurMa1978 & @josefree ,
I went through all the documentations & other linked pages for breaking change & retirement process. I understand it's importance and actions to be taken. Being from engineering team, I do believe involvement of PM from our service side is necessary for carrying out the process till completion. But before asking for their involvement, I need some clarifications. Can you please help me with the following concerns:-

• As required in the Migration strategy, do we need to have SDK of the replacement version ready beforehand ?
  -- If yes, we would need approval on this issue as it was opened with the proposal of namespace required in creating and publishing the SDK version corresponding to the replacement version.
• For breaking change board review here, I believe it is referring to PR for SDK repo. Can I raise a PR for review without the namespace being approved ?
• For our service, the current folder structure looks like this and for smooth onboarding of all customers in future once we publish SDKs for all languages, we are proposing the split of current namespace. Do we need to keep any other concerns in mind apart from the breaking change with this approach?

Please do let me know on the above as clarifications on these will help me proceed further in the correct path.

[ArthurMa1978]

Hi @ArthurMa1978 & @josefree , I went through all the documentations & other linked pages for breaking change & retirement process. I understand it's importance and actions to be taken. Being from engineering team, I do believe involvement of PM from our service side is necessary for carrying out the process till completion. But before asking for their involvement, I need some clarifications. Can you please help me with the following concerns:-

• As required in the Migration strategy, do we need to have SDK of the replacement version ready beforehand ?
  -- If yes, we would need approval on this issue as it was opened with the proposal of namespace required in creating and publishing the SDK version corresponding to the replacement version.
• For breaking change board review here, I believe it is referring to PR for SDK repo. Can I raise a PR for review without the namespace being approved ?
• For our service, the current folder structure looks like this and for smooth onboarding of all customers in future once we publish SDKs for all languages, we are proposing the split of current namespace. Do we need to keep any other concerns in mind apart from the breaking change with this approach?

Please do let me know on the above as clarifications on these will help me proceed further in the correct path.

1. No, we don't need to have the replacement ready beforehand.
2. You case is re-struct a existing RP, I don't think need a PR for SDK repo.
3. Yes, you can have the propose and discuss with breaking change board.

[srilipta-swain]

Hi @ArthurMa1978 & @josefree , I went through all the documentations & other linked pages for breaking change & retirement process. I understand it's importance and actions to be taken. Being from engineering team, I do believe involvement of PM from our service side is necessary for carrying out the process till completion. But before asking for their involvement, I need some clarifications. Can you please help me with the following concerns:-

• As required in the Migration strategy, do we need to have SDK of the replacement version ready beforehand ?
  -- If yes, we would need approval on this issue as it was opened with the proposal of namespace required in creating and publishing the SDK version corresponding to the replacement version.
• For breaking change board review here, I believe it is referring to PR for SDK repo. Can I raise a PR for review without the namespace being approved ?
• For our service, the current folder structure looks like this and for smooth onboarding of all customers in future once we publish SDKs for all languages, we are proposing the split of current namespace. Do we need to keep any other concerns in mind apart from the breaking change with this approach?

Please do let me know on the above as clarifications on these will help me proceed further in the correct path.

1. No, we don't need to have the replacement ready beforehand.
2. You case is re-struct a existing RP, I don't think need a PR for SDK repo.
3. Yes, you can have the propose and discuss with breaking change board.

Hi @ArthurMa1978 , thank you for clarification. Let me raise a request with the breaking change board.
Post the approval, I shall come back to get this approved right ?

[srilipta-swain]

Hi @ArthurMa1978 , I have raised the scenario for Breaking Change, meanwhile wanted to confirm on this.

Hi @ArthurMa1978 & @josefree , I went through all the documentations & other linked pages for breaking change & retirement process. I understand it's importance and actions to be taken. Being from engineering team, I do believe involvement of PM from our service side is necessary for carrying out the process till completion. But before asking for their involvement, I need some clarifications. Can you please help me with the following concerns:-

• As required in the Migration strategy, do we need to have SDK of the replacement version ready beforehand ?
  -- If yes, we would need approval on this issue as it was opened with the proposal of namespace required in creating and publishing the SDK version corresponding to the replacement version.
• For breaking change board review here, I believe it is referring to PR for SDK repo. Can I raise a PR for review without the namespace being approved ?
• For our service, the current folder structure looks like this and for smooth onboarding of all customers in future once we publish SDKs for all languages, we are proposing the split of current namespace. Do we need to keep any other concerns in mind apart from the breaking change with this approach?

Please do let me know on the above as clarifications on these will help me proceed further in the correct path.

1. No, we don't need to have the replacement ready beforehand.
2. You case is re-struct a existing RP, I don't think need a PR for SDK repo.
3. Yes, you can have the propose and discuss with breaking change board.

Hi @ArthurMa1978 , thank you for clarification. Let me raise a request with the breaking change board. Post the approval, I shall come back to get this approved right ?

[srilipta-swain]

Hi @ArthurMa1978 & @josefree
I raised the concern with Breaking Change Review Board, got the approval for the scenario raised. Please find the attached item.

Can you please help me with proceeding further ?

[srilipta-swain]

Hi @ArthurMa1978 & @josefree ,
Can you please share any updates ?

[ronniegeraghty]

Now we'll move on to the second phase of the MGMT Plane Namespace approval process, where the names will be shown to our architect team. The architects will have 1 week to make any objections to the namespaces. If there are no objections by end of business on 10/16 the names will be considered approved, and I will leave a comment on this issue state so.

[ronniegeraghty]

@srilipta-swain,
Our .NET architect has asked if there are any reasons we would not use a 4-level namespace for the .NET packages?
Ex:
Azure.ResourceManager.Migration.Assessment
Azure.ResourceManager.Migration.Modernization
Azure.ResourceManager.Migration.Hub

[ronniegeraghty]

@srilipta-swain,
Can you please let me know your thoughts on our architect's suggestion for the .NET namespaces?

[srilipta-swain]

@srilipta-swain, Our .NET architect has asked if there are any reasons we would not use a 4-level namespace for the .NET packages? Ex: Azure.ResourceManager.Migration.Assessment Azure.ResourceManager.Migration.Modernization Azure.ResourceManager.Migration.Hub

@ronniegeraghty based on the discussions in earlier issues, we proposed the following namespaces. If the architect's suggestion is for four-level namespaces, we are happy to do so.

[srilipta-swain]

Hi @ronniegeraghty ,
Do we have any update on this ?

[ronniegeraghty]

Hi @srilipta-swain,
The Architects have been discussing the namespaces.
Would your team be okay if the Java namespaces also used 4 level namespaces like .NET (but in the java pattern)?

[srilipta-swain]

Hi @srilipta-swain, The Architects have been discussing the namespaces. Would your team be okay if the Java namespaces also used 4 level namespaces like .NET (but in the java pattern)?

Hi @ronniegeraghty ,

Yes, if we do have any other teams similarly with 4 level namespaces in Java, we would be fine with it.

[ronniegeraghty]

I've updated the main description of this issue to reflect the change to 4 level namespaces in .NET and Java.
With that the names in the description of this issue are now approved.