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

Contributor Docs - Breaking Changes: update intro & clarify what constitutes a breaking change #28244

Merged
merged 3 commits into from
Dec 13, 2024
+6 −2
Merged

Contributor Docs - Breaking Changes: update intro & clarify what constitutes a breaking change #28244

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e3b7af0
Contributor Docs - Breaking Changes: update intro & clarify what cons…
katbyte Dec 10, 2024
d00ddde
Update contributing/topics/guide-breaking-changes.md
katbyte Dec 11, 2024
a27e005
Update contributing/topics/guide-breaking-changes.md
katbyte Dec 11, 2024
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
8 changes: 6 additions & 2 deletions contributing/topics/guide-breaking-changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
katbyte marked this conversation as resolved.
Show resolved Hide resolved

Types of breaking changes covered are:

- [Removing Resources or Data Sources](#removing-resources-or-data-sources)
- [Breaking Schema Changes](#breaking-schema-changes-and-deprecations)
Expand Down
Loading