Skip to content

Commit

Permalink
tfsdk: Clarify Attribute type DeprecationMessage documentation for Te…
Browse files Browse the repository at this point in the history 
…rraform 1.2.7 and later (#443)

Reference: hashicorp/terraform#31576
  • Loading branch information
@bflad
bflad authored Aug 11, 2022
1 parent 9e664c7 commit 4660530
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 26 deletions.
52 changes: 28 additions & 24 deletions tfsdk/attribute.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,35 +79,39 @@ type Attribute struct {
// file is sensitive.
Sensitive bool

// DeprecationMessage defines warning diagnostic details to display to
// practitioners configuring this Attribute. The warning diagnostic summary
// is automatically set to "Attribute Deprecated" along with configuration
// source file and line information.
// DeprecationMessage defines warning diagnostic details to display when
// practitioner configurations use this Attribute. The warning diagnostic
// summary is automatically set to "Attribute Deprecated" along with
// configuration source file and line information.
//
// This warning diagnostic is only displayed during Terraform's validation
// phase when this field is a non-empty string, when the Attribute is
// Required or Optional, and if the practitioner configuration attempts to
// set the attribute value to a known or unknown value (which may
// eventually be null). It cannot detect practitioner configuration values
// set directly to null, as there is no way for the framework to
// differentiate between an unset and null configuration due to how
// Terraform sends configuration information across the protocol, however
// this is unlikely in a real world configuration.
// Set this field to a practitioner actionable message such as:
//
// This field has no effect when the Attribute is Computed-only (read-only;
// not Required or Optional) and a practitioner attempts to reference
// this Attribute value in their configuration. There is a Terraform
// feature request to support this type of functionality:
// - "Configure other_attribute instead. This attribute will be removed
// in the next major version of the provider."
// - "Remove this attribute's configuration as it no longer is used and
// the attribute will be removed in the next major version of the
// provider."
//
// https://github.com/hashicorp/terraform/issues/7569
// In Terraform 1.2.7 and later, this warning diagnostic is displayed any
// time a practitioner attempts to configure a value for this attribute and
// certain scenarios where this attribute is referenced.
//
// Set this field to a practitioner actionable message such as:
// In Terraform 1.2.6 and earlier, this warning diagnostic is only
// displayed when the Attribute is Required or Optional, and if the
// practitioner configuration sets the value to a known or unknown value
// (which may eventually be null). It has no effect when the Attribute is
// Computed-only (read-only; not Required or Optional).
//
// Across any Terraform version, there are no warnings raised for
// practitioner configuration values set directly to null, as there is no
// way for the framework to differentiate between an unset and null
// configuration due to how Terraform sends configuration information
// across the protocol.
//
// Additional information about deprecation enhancements for read-only
// attributes can be found in:
//
// - "Configure other_attribute instead. This attribute will be removed
// in the next major version of the provider."
// - "Remove this attribute's configuration as it no longer is used and
// the attribute will be removed in the next major version of the
// provider."
// - https://github.com/hashicorp/terraform/issues/7569
//
DeprecationMessage string

Expand Down
4 changes: 2 additions & 2 deletions website/docs/plugin/framework/schemas.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ description](#markdowndescription), so too can individual attributes.

### DeprecationMessage

Individual attributes can be deprecated similar to resources, data sources, and providers. When the `DeprecationMessage` value is a non-empty string, the framework will automatically raise a warning diagnostic to practitioners if a configuration value (known or unknown) is detected for the attribute during Terraform's validation phase:
Individual attributes can be deprecated similar to resources, data sources, and providers. When the `DeprecationMessage` value is a non-empty string, the framework will automatically raise a warning diagnostic to practitioners if a configuration value (known or unknown) or reference is detected for the attribute during Terraform's validation phase:

```text
Warning: Attribute Deprecated
Expand All @@ -264,7 +264,7 @@ Warning: Attribute Deprecated

Use a practitioner actionable recommendation in `DeprecationMessage`, such as `"Configure other_attribute instead. This attribute will be removed in the next major version of the provider."` or `"Remove this attribute's configuration as it no longer is used and the attribute will be removed in the next major version of the provider."`.

~> **NOTE**: This warning diagnostic is only raised for configurable (`Required` or `Optional`) attributes when a configuration value is detected. A warning diagnostic is not raised for read-only (`Computed` only) attributes when referenced.
~> **NOTE**: In Terraform 1.2.6 and earlier, a deprecation warning diagnostic is only raised for configurable (`Required` or `Optional`) attributes when a configuration value is detected. A warning diagnostic is not raised for read-only (`Computed` only) attributes when referenced.

### Validators

Expand Down

0 comments on commit 4660530

Please sign in to comment.