Skip to content

Commit 5e6c790

Browse files
Update azure/Guidelines.md
Co-authored-by: Tom Kerkhove <[email protected]>
1 parent 422bacf commit 5e6c790

File tree

1 file changed

+14
-2
lines changed

1 file changed

+14
-2
lines changed

azure/Guidelines.md

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -757,10 +757,22 @@ When the [API Versioning](#API-Versioning) guidance above cannot be followed and
757757

758758
:white_check_mark: **DO** include this header in the operation's response _only if_ the operation will stop working in the future and the client _must take_ action in order for it to keep working. NOTE: We do not want to scare customers with this header.
759759

760-
:white_check_mark: **DO** make the header's value a semicolon-delimited string indicating a set of deprecations where each one indicates what is deprecating, when it is deprecating, and a URL to more information. For example:
760+
:white_check_mark: **DO** make the header's value a semicolon-delimited string indicating a set of deprecations where each one indicates what is deprecating, when it is deprecating, and a URL to more information.
761761

762+
Deprecations should use the following pattern:
762763
```text
763-
azure-deprecating: api-version=2009-27-07 will stop working on 2022-12-01 (https://azure.microsoft.com/en-us/updates/video-analyzer-retirement);TLS 1.0 & 1.1 will stop working on 2020-10-30 (https://azure.microsoft.com/en-us/updates/azure-active-directory-registration-service-is-ending-support-for-tls-10-and-11/)
764+
<description> will retire on <date> (`url`)
765+
```
766+
767+
Where the following placeholders should be provided:
768+
- `description`: a human-readable description of what is being deprecated
769+
- `date`: the target date that this will be deprecated. This should be expressed following the format in [ISO 8601](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.1.1), e.g. "2022-10-31".
770+
- `url`: a fully qualified url that the user can follow to learn more about what is being deprecated, preferably to Azure Updates.
771+
772+
For example:
773+
```text
774+
azure-deprecating: API version 2009-27-07 will retire on 2022-12-01 (https://azure.microsoft.com/en-us/updates/video-analyzer-retirement);TLS 1.0 & 1.1 will retire on 2020-10-30 (https://azure.microsoft.com/en-us/updates/azure-active-directory-registration-service-is-ending-support-for-tls-10-and-11/)
775+
```
764776
```
765777
766778
:no_entry: **DO NOT** introduce this header without this pattern without approval from [Azure Breaking Change Reviewers](mailto:[email protected]) and an official deprecation notice on [Azure Updates](https://azure.microsoft.com/updates/).

0 commit comments

Comments
 (0)