Versioning strategy for Graph extension

[jason-dou]

Creating this thread to discuss and seek feedback for the Graph extension versioning strategy. Feel free to share your thoughts!

Overview

Currently, in Bicep compiler, the Graph extension/provider is imported in the Bicep templates via the statement provider '[email protected]', where microsoftGraph is a single extension and the version is a placeholder hardcoded as 1.0.0. This brings two problems:

1. All v1.0 and beta resources will both be loaded in the templates.
2. Only the latest version of the Graph types can be used in the Bicep templates, which may contain breaking changes and are incompatible with the existing templates.

We plan to address the above issues with a versioning strategy for the Graph extension by utilizing the dynamic type loading feature, so you can choose the provider version for the templates.

Versioning

With dynamic type loading, extensions will be distributed using OCI registry (Azure/bicep#12111).

We plan to have two Graph type providers: microsoftGraphV1.0:a.b.c and microsoftGraphBeta:x.y.z. Only resources in v1.0 are in microsoftGraphV1.0, and only resources in beta are in microsoftGraphBeta. Version a.b.c and x.y.z increment independently and both follow the version semantics in the Version format and schema section.

You can use Graph types with the following import statements in your Bicep templates:

provider 'br:<repository-path>:microsoftGraphV1.0:a.b.c' 
provider 'br:<repository-path>:microsoftGraphBeta:x.y.z' 

resource resourceApp 'Microsoft.Graph/[email protected]' = { 
  uniqueName: 'ResourceApp' 
  displayName: 'Resource Application' 
} 

resource clientApp 'Microsoft.Graph/applications@beta' = { 
  uniqueName: 'ClientApp' 
  displayName: 'Client Application' 
} 

Version format and schema

The version format will be in a semantic format like x.y.z, following this comment Proposal: Versioning of provider artifacts and provider resources · Azure/bicep · Discussion #11894 (github.com). The rules to increment the version numbers are the following:

Version number Z accounts for minor or patch modifications to Graph resource types that do not introduce breaking changes. It should be incremented by 1 under the following circumstances:

• A new Graph resource type is added.

• A new property is added to an existing Graph resource type.

• A new API version of an existing Graph resource type is introduced.

Version number Y addresses breaking changes related to Graph resource types. It should be incremented by 1 under the following circumstances:

• Any of the existing Graph resource types undergoes modifications that breaks the existing contract, including

• The removal of an existing property

• The addition of a required property

• Changing the type of an existing property

• Narrowing the range of the possible values of an existing property

• Any of the existing resource types are removed.

Version number X represents significant changes in the Graph API or Bicep resource types.