with one click
deprecate-property
// Assist in deprecating or renaming a property, following the provider's breaking changes guide.
// Assist in deprecating or renaming a property, following the provider's breaking changes guide.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | deprecate-property |
| description | Assist in deprecating or renaming a property, following the provider's breaking changes guide. |
| triggers | ["deprecate property","rename property","change default value"] |
This skill assists in deprecating, renaming, or changing the behavior of a property in a way that will be finalized in the next major version.
Use the provider's major version feature flag (e.g., features.NextMajorVersion()) to maintain legacy behavior for the current major version. The focus is on making it as easy as possible to remove the unused code path. The default code path should be the new major version, and the legacy code path and schema modification to legacy should be gated behind a !features.NextMajorVersion() check so the future work to remove the legacy code path is minimal.
Note: Do not use in-lined anonymous functions in a property's schema definition to conditionally change the default value, validation function, etc. Regardless of the number of arguments changing, update the whole schema definition block rather than making inline changes.
"new_property": {
Type: pluginsdk.TypeString,
Optional: true,
},
// ...
if !features.NextMajorVersion() {
args["old_property"] = &pluginsdk.Schema{
Type: pluginsdk.TypeString,
Optional: true,
Computed: true, // Set both to Computed for renames
ConflictsWith: []string{"new_property"},
Deprecated: "`old_property` has been deprecated in favour of `new_property` and will be removed in the next major version of the Provider",
}
args["new_property"].Computed = true
args["new_property"].ConflictsWith = []string{"old_property"}
}
If you are changing a default value, update the default value in the main schema definition and patch over it with the old default using the feature flag:
"spark_version": {
Type: pluginsdk.TypeString,
Optional: true,
Default: "3.4",
},
// ...
if !features.NextMajorVersion() {
args["spark_version"].Default = "2.4"
}
Handle both properties in your logic. It is critical that you strictly follow the if !features.NextMajorVersion() { ... } else { ... } pattern. This ensures that the post-major release cleanup is as low effort as possible—consisting mostly of deleting the if block and keeping the else block.
To achieve this, duplicate the future major version logic inside the legacy if branch if necessary (e.g., when checking if the user supplied the new property early). The else block must contain only the pure, final major version code without any legacy conditionals.
if !features.NextMajorVersion() {
// 1. Check if they used the new property (optional in current major version)
if v, ok := d.GetOk("new_property"); ok && v.(string) != "" {
// Run future behavior manually for users adopting early
} else {
// Run legacy behavior
}
} else {
// Pure future behavior. The new property is required here.
// This block will cleanly become the main block when the new major version ships.
}
For Typed resources, ensure the old field in the model struct is tagged for removal.
type ExampleModel struct {
OldProperty string `tfschema:"old_property,removedInNextMajorVersion"`
NewProperty string `tfschema:"new_property"`
}
features.NextMajorVersion() feature flag.website/docs/5.0-upgrade-guide.markdown). Add an entry under ## Breaking changes in Resources (or Data Sources) in alphabetical order, detailing the removed property, the new property, or the new default values.**Note:** This property will do x in vNext notes in the documentation.ConflictsWith between old and new properties to prevent ambiguity.terraform-provider-azurerm/contributing/topics/guide-breaking-changes.md if working on AzureRM).When you modify a file that contains Terraform configuration (e.g., acceptance tests, markdown documentation), you MUST run the terrafmt fmt -f <file> command on the file to ensure the configuration meets Terraform's formatting standards.