Contributor Docs - Breaking Changes: update intro & clarify what cons…

…titutes a breaking change (#28244) * Contributor Docs - Breaking Changes: update intro & clarify what constitutes a breaking change * Update contributing/topics/guide-breaking-changes.md Co-authored-by: stephybun <[email protected]> * Update contributing/topics/guide-breaking-changes.md Co-authored-by: stephybun <[email protected]> --------- Co-authored-by: stephybun <[email protected]>
hashicorp · Dec 13, 2024 · 086d9ff · 086d9ff
1 parent 941b107
commit 086d9ff
Showing 1 changed file with 6 additions and 2 deletions.
diff --git 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 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 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:
 
 - [Removing Resources or Data Sources](#removing-resources-or-data-sources)
 - [Breaking Schema Changes](#breaking-schema-changes-and-deprecations)