Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Initial pass of versioning guidelines #564

Open
wants to merge 1 commit into
base: vNext
Choose a base branch
from
Open

Initial pass of versioning guidelines #564

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions azure/VersioningGuidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Azure Versioning Guidelines

## History

<details>
<summary>Expand change history</summary>

| Date | Notes |
| ----------- | -------------------------------------------------------------- |
| 2024-Nov-14 | Updated LRO guidelines |

</details>

## Guidelines

This document provides a "Dos and Don'ts" list for complying with the Azure Versioning and Breaking Change Policy,
as documented [internally](aka.ms/AzBreakingChangesPolicy) and [externally](https://learn.microsoft.com/azure/developer/intro/azure-service-sdk-tool-versioning).

:white_check_mark: **DO** thoroughly test the API as documented before merging to a production branch of the specs repo.

Testing helps avoid "BugFix" changes to the API definition. Testing should be done at the HTTP level as well as through generated SDKs.

:white_check_mark: **DO** retire all prior preview API versions when a new GA or preview API version is released.

:white_check_mark: **DO** contact the Azure Breaking Change Review board to coordinate communications to customers
when releasing an API version that will require retiring a prior version.

:white_check_mark: **DO** create a new preview API version for any features that should remain in preview following a new GA release.

:white_check_mark: **DO** use a date strictly later than the most recent GA API version when releasing
a new preview API version.

:white_check_mark: **DO** deprovision any API version that has been retired. Retired APIs versions should behave like
an unknown API version (see [ref](https://aka.ms/azapi/guidelines#versioning-api-version-unsupported)).

:white_check_mark: **DO** remove retired API versions from the azure-rest-api-specs repo.

:white_check_mark: **DO** review any change to service behavior that could disrupt customers with the Azure Breaking Changes review board, even if the change is not part of the API definition.

Some examples of behavior changes that must be reviewed are:
- Introducing or changing rate limits to be more restrictive than previously
- Changing the permissions required to successfully execute an operation

:no_entry: **DO NOT** change the behavior of an API version that is available to customers either in public preview or GA.
Changes in behavior should always be introduced in a new API version, with prior versions working as before.

:no_entry: **DO NOT** introduce breaking changes from a prior GA version just to satisfy ARM or Azure API guidelines.

Avoiding breaking changes in a GA API takes precedence over adherence to API guidelines and resolving linter errors.

:no_entry: **DO NOT** keep a preview feature in preview for more than 1 year; it must go GA (or be removed) within 1 year after introduction.