Add deprecation documentation (from Best Practices - SDKv2) #684
Conversation
|
Should we stack this new page under a section? I initially removed the section because there is only one page right now: |
| Given this sample resource: | ||
|
|
||
| ```go | ||
| package provider |
There was a problem hiding this comment.
Not sure if I correctly transcribed the original SDK deprecation code examples over, this is a first attempt 😄
Original docs: https://developer.hashicorp.com/terraform/plugin/sdkv2/best-practices/deprecations
| } | ||
| } | ||
|
|
||
| func (e *exampleWidgetResource) Create(ctx context.Context, req resource.CreateRequest, resp *resource.CreateResponse) { |
There was a problem hiding this comment.
Same as above, I transcribed the original SDK deprecation code examples over, but is there a better place to return this diag when deprecating an entire resource?
Original example: https://developer.hashicorp.com/terraform/plugin/sdkv2/best-practices/deprecations#provider-data-source-or-resource-removal
| 1. Add the new resource to the provider [`Resources`](/terraform/plugin/framework/providers#resources) function | ||
| 1. Follow the rest of the procedures in the [Provider Data Source or Resource Removal section](#provider-data-source-or-resource-removal). | ||
|
|
||
| ### Example Resource Renaming |
There was a problem hiding this comment.
Same as above, I transcribed the original SDK deprecation code examples over, but is there a better place to return this diag when deprecating an entire resource?
Original example: https://developer.hashicorp.com/terraform/plugin/sdkv2/best-practices/deprecations#provider-data-source-or-resource-rename
| 1. Add a [`DeprecationMessage`](/terraform/plugin/framework/handling-data/schemas#deprecationmessage-1) to the schema definition of the existing (now the "old") attribute, noting to use the new attribute in the message. | ||
| 1. Add `**Deprecated**` to the documentation of the existing (now the "old") attribute, noting to use the new attribute. | ||
| 1. Add a note to the documentation that either the existing (now the "old") attribute or new attribute must be configured. | ||
| 1. Add the type-specific [validator](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators) `{type}validator.ExactlyOneOf` to the schema definition of the new attribute, with a path expression matching the old attribute. This will ensure at least one of the attributes is configured, but present an error to the operator if both are configured at the same time. For example, an attribute of type string would use the [`stringvalidator.ExactlyOneOf`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator#ExactlyOneOf) validator. |
There was a problem hiding this comment.
I initially had this as the ConflictsWith validator, not sure which one is recommended
Original docs: https://developer.hashicorp.com/terraform/plugin/sdkv2/best-practices/deprecations#renaming-a-required-attribute
There was a problem hiding this comment.
I believe ConflictsWith or ExactlyOneOf can be used with equivalent results but I think I would lean towards the latter as seems from a semantic point of view to be more aligned with the intent.
austinvalle
changed the title
|
I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions. |
3 participants
contributes to hashicorp/terraform-plugin-sdk#1151
Related PRs:
Notes