From 9b53351a033d0ef41858ebf6442b9f3b4a2369ec Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Thu, 6 Jun 2024 14:11:56 -0700 Subject: [PATCH] Update directory-structure.md: clarify service, service group, uniform versioning. (#28929) --- .markdownlint.jsonc | 7 +- cSpell.json | 12 +- documentation/directory-structure.md | 270 ++++++++---------- documentation/glossary.md | 83 ++++++ .../typespec-structure-guidelines.md | 8 +- documentation/uniform-versioning.md | 95 ++++++ 6 files changed, 314 insertions(+), 161 deletions(-) create mode 100644 documentation/glossary.md create mode 100644 documentation/uniform-versioning.md diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 98657b7eff01..f4856b9b8949 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -31,5 +31,10 @@ // https://github.com/DavidAnson/markdownlint/blob/main/doc/md034.md // // We allow bare URLs e.g. to link to GitHub issues. - "MD034": false + "MD034": false, + + // MD041 - First line in a file should be a top-level heading + // + // We sometimes use "short link" table as first line. + "MD041": false } diff --git a/cSpell.json b/cSpell.json index 0af01c9ee4c6..e72217ed3b24 100644 --- a/cSpell.json +++ b/cSpell.json @@ -3,6 +3,8 @@ "language": "en", "words": [ "authnotrequired", + "azsdk", + "confidentialledger", "Creds", "fixdate", "frontends", @@ -878,7 +880,6 @@ "unittype" ] }, - { "filename": "**/specification/maps/data-plane/Microsoft.Maps/Render/preview/1.0/render.json", "words": [ @@ -1191,7 +1192,6 @@ "containerd" ] }, - { "filename": "**/specification/batch/data-plane/Microsoft.Batch/**/*.json", "words": [ @@ -1266,10 +1266,10 @@ { "filename": "**/specification/riskiq/data-plane/Microsoft.Easm/preview/2024-03-01-preview/easm.json", "words": [ - "Cisa", - "cisa", - "affected", - "AUTOCONFIRMED" + "Cisa", + "cisa", + "affected", + "AUTOCONFIRMED" ] }, { diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index c56b1a4e708a..d3564b6314b9 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -7,163 +7,142 @@ https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one --> - [`specification` directory structure](#specification-directory-structure) + - [Key concepts](#key-concepts) - [`specification` folder](#specification-folder) - - [`resource-manager` and `data-plane` folders](#resource-manager-and-data-plane-folders) - - [AutoRest configuration `README.md` files](#autorest-configuration-readmemd-files) - - [`stable` and `preview` folders](#stable-and-preview-folders) - - [A complete example directory structure of `specification/`](#a-complete-example-directory-structure-of-specificationazureteam) - - [Naming guidelines for `specification` folder contents](#naming-guidelines-for-specification-folder-contents) + - [`` folders](#typespecsrc-folders) + - [`resource-manager/` folder](#resource-managerrpns-folder) + - [`data-plane/` folders](#data-planegroupingdir-folders) + - [Service folder structure](#service-folder-structure) - [`specification/common-types`](#specificationcommon-types) - - [Advanced scenario: service group](#advanced-scenario-service-group) - - [Service group `common-types`](#service-group-common-types) - - [Versioning services in a service group](#versioning-services-in-a-service-group) - - [Deprecated structure and hand-written OpenAPI specs](#deprecated-structure-and-hand-written-openapi-specs) -# `specification` directory structure + - [Naming guidelines for `specification` folder contents](#naming-guidelines-for-specification-folder-contents) + - [About legacy, deprecated directory structure for services and service groups](#about-legacy-deprecated-directory-structure-for-services-and-service-groups) + - [Migrating from a singular service to service group in a legacy directory structure](#migrating-from-a-singular-service-to-service-group-in-a-legacy-directory-structure) + - [Deprecated directory structure and hand-written OpenAPI specs](#deprecated-directory-structure-and-hand-written-openapi-specs) +# `specification` directory structure This article describes the directory structure / folder layout of the `specification` folder. You may be also interested in following: + - [Specification index] - [Resource Provider list] > [!IMPORTANT] -> The structure described in this article is strictly enforced. There exist some exceptions for historical reasons. -> These exceptions are not allowed going forward. +> The structure described in this article is recommended. There exist some exceptions for historical reasons. +> These exceptions are strongly discouraged going forward. -## `specification` folder - -The `specification` folder is the root folder for all service specifications. - -Each child of the `specification` folder corresponds to a `service` specification for given Azure team. Here we denote such folder as ``. -In advanced cases for big teams the `` folder can host multiple services, known as `service group`. -Read [the relevant section](#advanced-scenario-service-group) for details. +## Key concepts -Given `` has following structure: +The directory structure is a reflection of a few key concepts. -- `/` (multiple folders) -- `/resource-manager` -- `/data-plane` - -The `/` folders contain the TypeSpec specification for the given `service` or `service group`. -You can find details on the name and contents of these folders in [TypeSpec directory structure]. -You can learn more about TypeSpec at [aka.ms/azsdk/typespec] and [aka.ms/typespec]. +Familiarize yourself with the concepts of `service`, `service group`, `grouping directory` and `uniform versioning` +as explained in the [glossary]. -## `resource-manager` and `data-plane` folders +## `specification` folder -The `/resource-manager` contains the ARM OpenAPI specifications emitted from TypeSpec in `/`. +The `specification` folder is the root folder for all `service` specifications. -The `resource-manager` folder has exactly one child folder whose name matches the **Resource Provider (RP) Namespace** (``), -such as `Microsoft.Automation` (full list of namespaces is [here][Resource Provider list]). -There is 1 to 1 correspondence between an RP and an RP namespace. -There must be **exactly one** RP namespace folder under given `resource-manager` folder. -We denote such folder as `resource-manager/`. +Each child of the `specification` folder corresponds to ``. +All the `service` (see [glossary]) specifications owned by that team are rooted in their `` folder. -The `/data-plane` contains the data-plane OpenAPI specifications emitted from TypeSpec in ``. -The `data-plane` folder has no child `` folder. However, it can have a set of `` folders. +Given `` folder has following structure: -## AutoRest configuration `README.md` files +- `/` (multiple `` folders are allowed) +- `/resource-manager/` (exactly one `` folder is allowed) +- `/data-plane/` (multiple `` folders are allowed) -Both the `/resource-manager` and `/data-plane` folders must contain an AutoRest configuration file, `README.md`. -Learn more about this file at [aka.ms/azsdk/autorest]. +### `` folders - +The `/` folders contain the TypeSpec specifications for the services owned by the team. -Each `README.md` describes a single `service` and is used as an SDK package and documentation for each version of the service. -Inside the `README.md` file there are lists of paths to OpenAPI spec `.json` files making up given service version. +The content of these folders is used as input to emit OpenAPI specifications +placed within `/resource-manager/` folder and `/data-plane/` folders. > [!NOTE] -> All OpenAPI specs for given service version (i.e. the list of paths in given `input-file:` block in the `README.md`) must have the same service version, -> which also means being in the same [API version lifecycle stage][aka.ms/azsdk/api-versions]. - -## `stable` and `preview` folders +> Some services may not have `` folders. In such case, these services OpenAPI specs are hand-written. +> This is legacy, deprecated practice and is not allowed going forward. -Both `/resource-manager/` and `/data-plane/` folders, in addition to containing `README.md`, also can contain -`stable` and `preview` folders. These folders contain OpenAPI specs in the `stable` and `preview` [lifecycle stages][aka.ms/azsdk/api-versions] -respectively, organized in `` subfolders for each service API version. For example, `/resource-manager//stable/` or -`/data-plane//preview/`. +You can find details on the name and contents of `` folders in [TypeSpec directory structure]. +You can learn more about TypeSpec at [aka.ms/azsdk/typespec] and [aka.ms/typespec]. -Each such API version folder directly contains a set of `.json` files containing OpenAPI specs emitted from TypeSpec, as well as an `examples` child folder -with `.json` files having the contents of [`x-ms-examples`] referenced from the OpenAPI specs. +### `resource-manager/` folder -## A complete example directory structure of `specification/` +The `/resource-manager/` is a folder corresponding to ARM **Resource Provider (RP) namespace**. -Putting everything together discussed, the directory structure of a singular `specification//` is as follows: +An example RPNS is `Microsoft.Automation`. A list of RPs can be found in the [Resource Provider list]. -``` yaml -/1/... -/2/... # multiple '' folders +This folder corresponds to a `service group` (see [glossary]) for all ARM services owned by the team. -/resource-manager/README.md -/resource-manager//stable//*.json -/resource-manager//stable//examples/*.json - // ... # multiple '' folders -/resource-manager//preview//*.json -/resource-manager//preview//examples/*.json - // ... # multiple '' folders +An `` folder has one or more child `` folders corresponding to the services belonging +to the `service group` represented by the `` folder. -/data-plane/README.md -/data-plane//stable//*.json -/data-plane//stable//examples/*.json - // ... # multiple '' folders -/data-plane//preview//*.json -/data-plane//preview//examples/*.json - // ... # multiple '' folders - // ... # multiple '' folders +For example, [`specification/containerservice/resource-manager/Microsoft.ContainerService/aks`] +is a folder for the `aks` service within the `Microsoft.ContainerService` ARM Resource Provider namespace. -``` +> [!NOTE] +> Many Azure teams that have one ARM service instead of rooting it in +> `specification//resource-manager//` root it in +> `specification//resource-manager`. +> This is legacy, deprecated structure and is strongly discouraged going forward. -As a specific example of the above, consider [`specification/confidentialledger`] `` which has the following structure: +In addition, the `` folder may contain `common-types` child folder that usually is of +form `common-types/v/common.json` and contains types shared across API versions. +E.g. [`Microsoft.Compute/common-types`]. -``` yaml +### `data-plane/` folders -# ===== s +The `/data-plane` folder is the equivalent +of `/resource-manager` but with following distinctions: -/Microsoft.CodeTransparency/ -/Microsoft.ManagedCcf/ +- `/data-plane` pertains to data-plane service APIs, not ARM service APIs. +- `/data-plane` has no concept of Resource Provider Namespace (``). + Instead, it has or more `` child folders (see also [glossary]). -# ===== data-plane +Each `` folder has one or more child `` folders corresponding to the services grouped +in given ``. -/data-plane/README.md +> [!NOTE] +> Many Azure teams that have one data-plane service instead of rooting it in +> `specification//data-plane//` root it in +> `specification//data-plane`. +> This is legacy, deprecated structure and is strongly discouraged going forward. -# ----- : Microsoft.CodeTransparency +## Service folder structure -/data-plane/Microsoft.CodeTransparency/preview/2024-01-11-preview -/data-plane/Microsoft.CodeTransparency/preview/2024-01-11-preview/examples +As described above, ARM service folder path is: -# ----- : Microsoft.ConfidentialLedger +`specification//resource-manager//` -/data-plane/Microsoft.ConfidentialLedger/stable -/data-plane/Microsoft.ConfidentialLedger/stable/2022-05-13 -/data-plane/Microsoft.ConfidentialLedger/stable/2022-05-13/examples +while data-plane service folder path is: -/data-plane/Microsoft.ConfidentialLedger/preview -/data-plane/Microsoft.ConfidentialLedger/preview/2023-01-18-preview -/data-plane/Microsoft.ConfidentialLedger/preview/2023-01-18-preview/examples -# ... more previews here +`specification//data-plane//`. -# ----- : Microsoft.ManagedCcf +A service folder has the following elements: -/data-plane/Microsoft.ManagedCcf/preview/2023-06-01-preview -/data-plane/Microsoft.ManagedCcf/preview/2023-06-01-preview/examples +- The [AutoRest config `README.md` file]. See also section about it in [uniform versioning article]. +- Additional AutoRest config `README.md` files specific to given language SDK. +- The `stable` and `preview` folders if applicable. -# ===== resource-manager +The `stable` and `preview` folders contain OpenAPI specs in the `stable` and `preview` [lifecycle stages][aka.ms/azsdk/api-versions] +respectively, organized in `` subfolders for each service API version. -/resource-manager/README.md +For example: -# ----- resource-manager RP Namespace (): Microsoft.ConfidentialLedger +- `/resource-manager///stable/` +- `/resource-manager///preview/` +- `/data-plane///stable/` +- `/data-plane///preview/` -/resource-manager/Microsoft.ConfidentialLedger/stable/2022-05-13 -/resource-manager/Microsoft.ConfidentialLedger/stable/2022-05-13/examples +Each such API version folder directly contains a set of `.json` files containing OpenAPI specs emitted from TypeSpec, +as well as an `examples` child folder with `.json` files having the contents of [`x-ms-examples`] referenced +from the OpenAPI specs. -/resource-manager/Microsoft.ConfidentialLedger/preview/2023-06-28-preview -/resource-manager/Microsoft.ConfidentialLedger/preview/2023-06-28-preview/examples -# ... more previews here -/resource-manager/Microsoft.ConfidentialLedger/preview/2020-12-01-preview -/resource-manager/Microsoft.ConfidentialLedger/preview/2020-12-01-preview/examples +Read [API versioning guidelines] to learn more. -``` +## `specification/common-types` -For another example, see [`specification/eventgrid`]. +The special directory of [`specification/common-types`] contains shared definitions that can be reused across all +Azure team services in their `specification` child folders. ## Naming guidelines for `specification` folder contents @@ -173,75 +152,66 @@ For another example, see [`specification/eventgrid`]. - For file names, any casing is allowed. - When in doubt, mimic naming of the examples provided in this article. -## `specification/common-types` - -The special directory of [`specification/common-types`] contains shared definitions that can be reused across all Azure team services in their -`specification` child folders. - -## Advanced scenario: service group +## About legacy, deprecated directory structure for services and service groups -In case of big Azure teams, their `specification/` hosts multiple services, together known as `service group`. -The main difference between one service and a service group is how they are presented to Azure customers: -One service has one SDK package and one documentation portal, while a service group has separate SDK package for each service and separate documentation. +Many teams follow a legacy, deprecated directory structure which usually has following differences: -For example, [`specification/containerservice`] is a `service group` for both `aks` and `fleet` services. +- If a team owns only one service, instead of rooting it in `specification//resource-manager//`, + it is rooted in`specification//resource-manager`. +- If a team first owned one service and then expanded to a service group, + it contains mixture of both the deprecated structure (for the first service) as well as the correct structure + (for the 2nd and following services). -The doc for `aks` is [Azure Kubernetes Service]. It points to aks REST reference e.g. for [API version `2024-01-01`][aks REST reference 2024-01-01], -which corresponds to [`specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01`]. +This legacy structure is strongly discouraged going forward. -The doc for `fleet` is [Azure Kubernetes Fleet Manager]. It point to fleet REST reference, e.g. for [API version `2023-10-15`][fleet REST reference 2023-10-15], -which corresponds to [`specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15`]. +## Migrating from a singular service to service group in a legacy directory structure -Using our example, note the most important directory structure difference of a `service group` scenario as compared to singular `service`: +In case an Azure SDK team owns a singular service following the legacy, deprecated layout, and wants to expand to a full +service group, it can do the following: -- The `resource-manager/Microsoft.ContainerService` folder has multiple child service folders which contain `stable` and `preview` folders for each service, - instead of directly containing `stable` and `preview` folders. -- Each of the `aks` and `fleet` subfolders have their own `README.md` file, instead of there being one `README.md` in the `resource-manager` folder. - As a result, the SDKs of these services are separate. +- Keep the existing service as-is, without any changes. +- Introduce the new services using the new, correct structure. -### Service group `common-types` +## Deprecated directory structure and hand-written OpenAPI specs -A service group can also introduce its own set of `common-types` which are too general to be shared across all Azure teams but common enough to be -shared across all services in given service group. For an example, see [`Microsoft.Compute/common-types`]. - -### Versioning services in a service group - -The versioning policy for API and SDK packages applies independently to each service in the service group. -This means that each service in the service group must obey the same versioning rules as it were a singular service. -However, multiple separate services can have different versioning cycles, including different SDK packages. Refer to the aforementioned `aks` and `fleet` -services for examples of different versioning cycles in a service group. - -## Deprecated structure and hand-written OpenAPI specs - -As mentioned at the beginning of this article, for historical reasons, some `specification/` folders may +As mentioned multiple times in this article, for historical reasons, some `specification/` folders may violate some of the constraints presented in this article. This includes violations like: - More deeply nested subfolders than allowed. +- `README.md` placed in a wrong folder (thus incorrectly denoting it as a `service` folder). +- Lack of `` directory for given service path. - Incorrect lack of `-preview` suffix in `preview` API versions. +- Multiple `` subfolders of `resource-manager` folder. - Mixing of `stable` and `preview` API versions in the same folder subtree. - Mixing of multiple API versions in given `README.md` package, including mixing of multiple API version lifecycle stages. -In addition, some `` folders have OpenAPI specs that have been written manually instead of emitted from TypeSpec. -In some cases the folders have mixture of manually-written and TypeSpec-emitted OpenAPI specs. +In addition, some `` folders have OpenAPI specs that have been written manually instead of emitted from +TypeSpec. In some cases the folders have mixture of manually-written and TypeSpec-emitted OpenAPI specs. -All of the aforementioned cases are considered legacy and are not allowed going forward. +All of the aforementioned cases are considered legacy & deprecated, and are strongly discouraged going forward. [`Microsoft.Compute/common-types`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/common-types/ [`specification/common-types`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types +[`specification/containerservice/resource-manager/Microsoft.ContainerService/aks`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks +[`x-ms-examples`]: https://azure.github.io/autorest/extensions/#x-ms-examples +[aka.ms/azsdk/api-versions]: https://aka.ms/azsdk/api-versions +[aka.ms/azsdk/typespec]: https://aka.ms/azsdk/typespec +[aka.ms/typespec]: https://aka.ms/typespec +[API versioning guidelines]: https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#api-versioning +[AutoRest config `README.md` file]: https://aka.ms/azsdk/autorest +[glossary]: ./glossary.md +[Resource Provider list]: https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service +[Specification index]: https://azure.github.io/azure-sdk/releases/latest/all/specs.html +[TypeSpec directory structure]: https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md +[uniform versioning article]: ./uniform-versioning.md + + [`specification/confidentialledger`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/confidentialledger [`specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01 [`specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15 [`specification/containerservice`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice [`specification/eventgrid`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/eventgrid -[`x-ms-examples`]: https://azure.github.io/autorest/extensions/#x-ms-examples -[aka.ms/azsdk/api-versions]: https://aka.ms/azsdk/api-versions [aka.ms/azsdk/autorest]: https://aka.ms/azsdk/autorest -[aka.ms/azsdk/typespec]: https://aka.ms/azsdk/typespec -[aka.ms/typespec]: https://aka.ms/typespec [aks REST reference 2024-01-01]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01 [Azure Kubernetes Fleet Manager]: https://learn.microsoft.com/en-us/azure/kubernetes-fleet/ -[Azure Kubernetes Service]: https://learn.microsoft.com/en-us/azure/aks/ [fleet REST reference 2023-10-15]: https://learn.microsoft.com/en-us/rest/api/fleet/operation-groups?view=rest-fleet-2023-10-15 -[Resource Provider list]: https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service -[Specification index]: https://azure.github.io/azure-sdk/releases/latest/all/specs.html -[TypeSpec directory structure]: https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md diff --git a/documentation/glossary.md b/documentation/glossary.md new file mode 100644 index 000000000000..d55bbf11b9ff --- /dev/null +++ b/documentation/glossary.md @@ -0,0 +1,83 @@ +# Glossary + +This article defines some of the terms used in the articles under `documentation` directory. + +## Grouping directory + +A `grouping directory`, denoted as `` in the [directory structure article], is a root folder for +a set of data-plane `service` folders. It is a subfolder of `data-plane` folder. + +Each `service` in given `grouping directory` must [**version uniformly**][uniform versioning article] but each `service` +within a `grouping directory` can version independently of each other. + +A `grouping directory` can be seen as a more free-form equivalent of the ARM `service group`, but for data-plane services. + +Specifically, all services grouped in given `groping directory` do not share any ARM **Resource Provider (RP) namespace** +and are not related to ARM in any way. + +## Resource type + +In case of ARM, a `service` is a collection of `resource types` or `resource type groups`. + +## Service + +A `service` is a set of operation endpoints (typically HTTP REST API endpoints) +that [**version uniformly**][uniform versioning article]. + +A `service` corresponds to a cohesive, uniformly versioned experience for the customer with HTTP REST API surface, +documentation portal and language SDKs. For example, [Azure Kubernetes Service]. + +In this repository, an ARM service has a path of form: + +`specification//resource-manager//` + +where `` stands for ARM **Resource Provider (RP) namespace**. + +A data-plane service has a path of form: + +`specification//data-plane//` + +> [!NOTE] +> Some existing services follow different directory structure layouts. +> All such layouts are legacy, deprecated, and not allowed going forward. + +For example, [`specification/containerservice/resource-manager/Microsoft.ContainerService/aks`] +is a folder for the `aks` service within the `Microsoft.ContainerService` ARM Resource Provider namespace. + +You can learn more about how a `service` maps to its directory in the [directory structure article]. + +## Service group + +A `service group` is a set of services that share a common ARM **Resource Provider (RP) namespace**, `RPNS`. + +Each `service` in given `service group` must [**version uniformly**][uniform versioning article] but each `service` +within a `service group` can version independently of each other. + +A `service group` has a path of form: + +`specification//resource-manager/` + +as such, it corresponds to ARM Resource Provider Namespace. + +Example service group: + +[`specification/containerservice/resource-manager/Microsoft.ContainerService`] + +which is composed of two services, [`aks`] and [`fleet`]. + +> [!NOTE] +> Previously `service group` was erroneously used in reference to services like `aks`. This is incorrect. + +You can learn more about how a `service group` maps to its directory in the [directory structure article]. + +## Uniform versioning + +See [uniform versioning article]. + +[`aks`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks +[`fleet`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/fleet +[`specification/containerservice/resource-manager/Microsoft.ContainerService/aks`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks +[`specification/containerservice/resource-manager/Microsoft.ContainerService`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService +[Azure Kubernetes Service]: https://learn.microsoft.com/en-us/azure/aks/ +[directory structure article]: ./directory-structure.md +[uniform versioning article]: ./uniform-versioning.md diff --git a/documentation/typespec-structure-guidelines.md b/documentation/typespec-structure-guidelines.md index 92ee3450ea70..f7ff9359f922 100644 --- a/documentation/typespec-structure-guidelines.md +++ b/documentation/typespec-structure-guidelines.md @@ -4,9 +4,9 @@ - [Service folder structure](#service-folder-structure) - [Libraries for service groups](#libraries-for-service-groups) - [Specification versioning](#specification-versioning) - - [Organizing services in folders](#organizing-services-in-folders) - - [Utilizing feature branches](#utilizing-feature-branches) - - [Publishing specifications](#publishing-specifications) + - [Organizing services in folders](#organizing-services-in-folders) + - [Utilizing feature branches](#utilizing-feature-branches) + - [Publishing specifications](#publishing-specifications) # Guidelines for TypeSpec project repositories @@ -18,7 +18,7 @@ This document provides guidelines for managing TypeSpec projects for Azure. It o The structure of TypeSpec project repositories starts with the [specification](https://aka.ms/azsdk/spec-dirs) folder, serving as the root for all service specifications. Each child folder, denoted as ``, corresponds to a service specification for a specific Azure team. In more complex scenarios, such as larger teams, the `` folder can host multiple services, forming what is known as a service group. -The `` folder can include multiple ``s, each containing the TypeSpec specification for a given service or service group. +The `` folder can include multiple `` folders, each containing the TypeSpec specification for a given service or service group. A given TypeSpec project folder can represent various scenarios: diff --git a/documentation/uniform-versioning.md b/documentation/uniform-versioning.md new file mode 100644 index 000000000000..923e8c2c0ed4 --- /dev/null +++ b/documentation/uniform-versioning.md @@ -0,0 +1,95 @@ +# Uniform versioning + +> [!NOTE] +> This article uses terminology defined in the [glossary], like `service` or `service group`. + +A `service` **must version uniformly**. + +In brief, it means: + +> The service, its set of operation endpoints (typically HTTP REST API endpoints), its documentation, and any SDK referencing it, all must version in lockstep. +> If a new service API version is released, also a new documentation reference must be released to describe it. +> Similarly, a new version of given SDK package must be released to refer to the new service version. + +Each `service` within a `service group` can version independently of each other. + +## Uniform versioning rules + +All of the rules listed here apply both for OpenAPI specs emitted from TypeSpec as well as for hand-written OpenAPI specs. + +**Uniform versioning** prescribes the following + +1. Any deployed service operation endpoint must belong to an API version. An API version once deployed is immutable. + Its behavior or constituent operations cannot be changed. +2. Any given service API version can be composed only of HTTP API operations and ARM resource types (if applicable) + that have the same API version. +3. Any documentation pertaining to the service and any SDKs generated from the service must pertain to only + one service version. +4. The service version must be always represented in its entirety; any SDK or documentation referring to the service + must encompass all of it. +5. The `common-types` OpenAPI definition shared across multiple services can version independently of the service. + However, the rule that API version is immutable still must be observed. + As such, when versioning `common-types`, previous API versions will remain immutable because new API versions must be created. + +## Uniform versioning implications + +The **uniform versioning** has several implications and implementation decisions supporting it. + +### API versions + +- The service is effectively defined as a series of consecutive API versions. +- Each API version is represented by a pair of folders representing its lifecycle stage and a date, + like `stable/2024-03-05` or `preview/2024-05-15-preview`. +- Each API version date must be later than the previous date. +- `stable` and `preview` API versions cannot have the same date. This would prevent API users from knowing + which one is later one. +- Moving to `stable` from `preview` by removing `-preview` suffix is not allowed. + In such case, at least one day must be added to the `stable` API version. + +### Directory structure + +- The entirety of given API service specification must be placed inside its folder, e.g. `stable/2024-03-05`. + The service consists of operation endpoints defined in OpenAPI spec `.json` files placed in its API version folder. +- Learn more in [directory structure article]. + +### No API version mixing within a service + +- Nowhere within a service, documentation for it, or SDK referencing it, + can multiple service API versions be mixed. as such: + - `preview` API versions cannot be mixed with `stable` API versions. + - No HTTP API endpoint for given API version can have any kind of dependency on service endpoint from any other API version. + - The above apply to a stand-alone service as well as to a service that is a member of a `service group`. + +### API version mixing across services in a service group + +- Each `service` within a `service group` can version independently of each other. +- Each `service` within a `service group` must observe the **uniform versioning rules** within its own scope. + +### AutoRest configuration for SDK generation (`README.md` files) + +- Any [AutoRest config `README.md` file] definition for the service must have tags corresponding to the API versions + present in the directory structure. +- Each of the API version tags must include **all** OpenAPI spec `.json` files for given API version. +- Each of the API version tags must include **only** OpenAPI spec `.json` files for given API version. +- Each `README.md` describes a single `service` and is used as an SDK package and documentation for each version of the service. +- All OpenAPI specs for given `service` API version (i.e. the list of paths in given `input-file:` block for given API version tag in the `README.md`) + must have the same service version, which also means being in the same [API version lifecycle stage]. + +### Versioning of `common-types` + +- All the shared OpenAPI definitions (i.e. `common-types`) the service depends on must have the same version, + [e.g. `v6`][common-types v6], but it can be different from the version of the service. +- Updating `common-types` version requires updating the API version. + For example, if `common-types` published an updated version of `v7`, + then if the service wants to take dependency on it, it can only do it in + a new version. For example, `2024-04-17`. + Because the service version is now `2024-04-17`, all the OpenAPI specification `.json` files the service is composed + of must have the same version of `2024-04-17` and the `info.version` property must say `2024-04-17`. + In addition, a new SDK must be generated from the service, and new documentation published, both tagged with + service version `2024-04-17`. + +[API version lifecycle stage]: https://aka.ms/azsdk/api-versions +[AutoRest config `README.md` file]: https://aka.ms/azsdk/autorest +[common-types v6]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types/resource-management/ +[directory structure article]: ./directory-structure.md +[glossary]: ./glossary.md