Board Review: Management Plane Namespace Review Microsoft.PortalServices/CopilotSettings

[karanvsingh1]

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 Portal Intelligent Experiences
• Main contacts: Eugene Bykov (eugeneby), Karan Singh (karanvsingh), Asher Garland (asgar), Ryan Benson (rbenson)
• Expected code complete date: 03/01/25
• Expected release date: 03/28/25

About the Service (required)

• Link to documentation introducing/describing the service: https://learn.microsoft.com/en-us/azure/copilot/manage-access
• Link to the service REST APIs Specs: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/portalservices/resource-manager/Microsoft.PortalServices/copilotSettings
• Link to GitHub issue for previous review sessions, if applicable: N/A

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.PortalServicesCopilot
• Java: azure-resourcemanager-portalservicescopilot (com.azure.resourcemanager.portalservicescopilot)
• Go/Golang: sdk/resourcemanager/portalservicescopilot/armportalservicescopilot
• JavaScript: @azure/arm-portalservicescopilot
• Python: azure-mgmt-portalservicescopilot

Thank you!

[ArthurMa1978]

Hey @karanvsingh1 , I have a question regarding your service. Are you aware that all new services introduced after last February should define their spec using TypeSpec? (This was communicated in the formal email titled "ARM RP Platform Notification - TypeSpec Enforcement for New RP APIs").

Additionally, for your namespace, we should avoid using a four-level name. Therefore, I suggest the namespace should be:

• .NET: Azure.ResourceManager.PortalServicesCopilotSettings
• Java: azure-resourcemanager-portalservicescopilotsettings
• Go/Golang: sdk/resourcemanager/portalservicescopilotsettings/armportalservicescopilotsettings
• JavaScript: @azure/arm-portalservicescopilotsettings
• Python: azure-mgmt-portalservicescopilotsettings

[karanvsingh1]

Hey @ArthurMa1978

Our PortalServices RP's CopilotSettings resource type spec is defined here in TypeSpec:

Link to TypeSpec

These namespace suggestions are fine with our team, what are the next steps to proceed with finalizing this and what is the timeline here?

[ArthurMa1978]

Ok, then we can move to next step @ronniegeraghty .

[ronniegeraghty]

With Arthur's approval on the namespaces, we now move to the Architect Review. Our SDK Architect team will now review the namespaces and either give their approval or make an objection, if an Architect from each language approves the namespaces or if no Architect has made any objections and 1 week has passed, the namespaces will be considered approved.

[qiaozha]

what is the relationship between copilotSettings and extensions? do you expect them to be two different SDKs and version independently?
If yes, I think you should have readme file in each subfolder instead of having one readme file and put them into the same tag here.
If no, which means there's only one SDK for Microsoft.PortalServices per language?

/cc @JeffreyRichter

[qiaozha]

Another thing I have noticed is that this service is trying to stable the same api version for latest preview, which is violating the rule https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#versioning-use-later-date-2 we should have a newer version than the preview for the GA, so that customers could know which one is latest when they are picking among all the available versions.
/cc @josefree

[karanvsingh1]

Another thing I have noticed is that this service is trying to stable the same api version for latest preview, which is violating the rule https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#versioning-use-later-date-2 we should have a newer version than the preview for the GA, so that customers could know which one is latest when they are picking among all the available versions. /cc @josefree

@qiaozha We were not aware of this as no-one brought it up during our TypeSpec API GA versioning review and it got approved. And we have already made all the backend changes and resource registration changes to handle this version.

Is it possible to re-introduce another stable version or can we get exception here? Can we proceed with SDK release while this is going on?

CC: @ashergarland

[ronniegeraghty]

Another thing I have noticed is that this service is trying to stable the same api version for latest preview, which is violating the rule https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#versioning-use-later-date-2 we should have a newer version than the preview for the GA, so that customers could know which one is latest when they are picking among all the available versions. /cc @josefree

@qiaozha We were not aware of this as no-one brought it up during our TypeSpec API GA versioning review and it got approved. And we have already made all the backend changes and resource registration changes to handle this version.

Is it possible to re-introduce another stable version or can we get exception here? Can we proceed with SDK release while this is going on?

CC: @ashergarland

@JeffreyRichter, Can you comment on this from an API Review point of view?

[JeffreyRichter]

Yes, @qiaozha and I reviewed this together over Teams 2 days ago. She is very correct. Azure should NEVER ship a stable and preview version with the same date value.