From e3b7af0ccfe2d5ab48c65384b76ddd2f40723b03 Mon Sep 17 00:00:00 2001 From: kt Date: Tue, 10 Dec 2024 15:21:04 -0800 Subject: [PATCH 1/3] Contributor Docs - Breaking Changes: update intro & clarify what constitutes a breaking change --- contributing/topics/guide-breaking-changes.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/contributing/topics/guide-breaking-changes.md b/contributing/topics/guide-breaking-changes.md index f6e815282f79..7b1e5487160e 100644 --- a/contributing/topics/guide-breaking-changes.md +++ b/contributing/topics/guide-breaking-changes.md @@ -1,8 +1,12 @@ # Guide: Breaking Changes and Deprecations -To keep up with and accommodate the changing pace of Azure, the provider needs to be able to introduce and handle breaking changes. We can safely introduce breaking changes into the provider using the major release feature flag, for the next major release that would the `features.FivePointOhBeta` flag which is available in the provider today. +To keep up with and accommodate the changing pace of Azure, the provider needs to be able to gracefully introduce and handle breaking changes. A "breaking change" within the provider is considered to be anything that requires an end user to modify previously valid terraform configuration after a provider upgrade to either deploy new resources or to maintain existing deployments. Even if a change does not affect the user's current deployment, it is still considered a breaking change if it requires the user to modify their configuration to deploy new resources. -This guide includes several topics on how to do common deprecations and breaking changes in the provider using this feature flag, as well as additional guidance on how to deal with changing default values in the Azure API. +The `azurerm` provider attempts to be as "surface stable" as possible during minor and patch releases meaning breaking changes are typically only made during major releases, however exceptions are sometimes made for minor or necessary breaking changes. Terraform users rely on the stability of Terraform providers as not only can configuration changes be costly to make, test, and deploy they can also affect downstream tooling such as modules. Even as part of a major release, breaking changes that are overly large or have little benefit can delay users upgrading to the next major version. + +Generally we can safely introduce breaking changes into the provider for the major release using a feature flag. For the next major release that would the `features.FivePointOhBeta()` flag which is available in the provider today. This guide includes several topics on how to do common deprecations and breaking changes in the provider using this feature flag, as well as additional guidance on how to deal with changing default values in the Azure API. + +Types of breaking changes covered are: - [Removing Resources or Data Sources](#removing-resources-or-data-sources) - [Breaking Schema Changes](#breaking-schema-changes-and-deprecations) From d00ddde74408979f913ce3c8c00a2a1158c4c7b8 Mon Sep 17 00:00:00 2001 From: kt Date: Wed, 11 Dec 2024 08:32:33 -0800 Subject: [PATCH 2/3] Update contributing/topics/guide-breaking-changes.md Co-authored-by: stephybun --- contributing/topics/guide-breaking-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/topics/guide-breaking-changes.md b/contributing/topics/guide-breaking-changes.md index 7b1e5487160e..5dabf79002ab 100644 --- a/contributing/topics/guide-breaking-changes.md +++ b/contributing/topics/guide-breaking-changes.md @@ -2,7 +2,7 @@ To keep up with and accommodate the changing pace of Azure, the provider needs to be able to gracefully introduce and handle breaking changes. A "breaking change" within the provider is considered to be anything that requires an end user to modify previously valid terraform configuration after a provider upgrade to either deploy new resources or to maintain existing deployments. Even if a change does not affect the user's current deployment, it is still considered a breaking change if it requires the user to modify their configuration to deploy new resources. -The `azurerm` provider attempts to be as "surface stable" as possible during minor and patch releases meaning breaking changes are typically only made during major releases, however exceptions are sometimes made for minor or necessary breaking changes. Terraform users rely on the stability of Terraform providers as not only can configuration changes be costly to make, test, and deploy they can also affect downstream tooling such as modules. Even as part of a major release, breaking changes that are overly large or have little benefit can delay users upgrading to the next major version. +The `azurerm` provider attempts to be as "surface stable" as possible during minor and patch releases meaning breaking changes are typically only made during major releases, however exceptions are sometimes made for minor releases when the breaking change is deemed necessary or is unavoidable. Terraform users rely on the stability of Terraform providers as not only can configuration changes be costly to make, test, and deploy they can also affect downstream tooling such as modules. Even as part of a major release, breaking changes that are overly large or have little benefit can delay users upgrading to the next major version. Generally we can safely introduce breaking changes into the provider for the major release using a feature flag. For the next major release that would the `features.FivePointOhBeta()` flag which is available in the provider today. This guide includes several topics on how to do common deprecations and breaking changes in the provider using this feature flag, as well as additional guidance on how to deal with changing default values in the Azure API. From a27e005206f3c86c97980f82983b711524b94680 Mon Sep 17 00:00:00 2001 From: kt Date: Wed, 11 Dec 2024 08:32:38 -0800 Subject: [PATCH 3/3] Update contributing/topics/guide-breaking-changes.md Co-authored-by: stephybun --- contributing/topics/guide-breaking-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/topics/guide-breaking-changes.md b/contributing/topics/guide-breaking-changes.md index 5dabf79002ab..1bc1335650d1 100644 --- a/contributing/topics/guide-breaking-changes.md +++ b/contributing/topics/guide-breaking-changes.md @@ -4,7 +4,7 @@ To keep up with and accommodate the changing pace of Azure, the provider needs t The `azurerm` provider attempts to be as "surface stable" as possible during minor and patch releases meaning breaking changes are typically only made during major releases, however exceptions are sometimes made for minor releases when the breaking change is deemed necessary or is unavoidable. Terraform users rely on the stability of Terraform providers as not only can configuration changes be costly to make, test, and deploy they can also affect downstream tooling such as modules. Even as part of a major release, breaking changes that are overly large or have little benefit can delay users upgrading to the next major version. -Generally we can safely introduce breaking changes into the provider for the major release using a feature flag. For the next major release that would the `features.FivePointOhBeta()` flag which is available in the provider today. This guide includes several topics on how to do common deprecations and breaking changes in the provider using this feature flag, as well as additional guidance on how to deal with changing default values in the Azure API. +Generally we can safely introduce breaking changes into the provider for the major release using a feature flag. For the next major release that would be the `features.FivePointOhBeta()` flag which is available in the provider today. This guide includes several topics on how to do common deprecations and breaking changes in the provider using this feature flag, as well as additional guidance on how to deal with changing default values in the Azure API. Types of breaking changes covered are: