From ea92c29233295f736d82df6703c809af2d6e283f Mon Sep 17 00:00:00 2001 From: Brian Flad Date: Wed, 27 Jul 2022 17:02:44 -0400 Subject: [PATCH] helper/schema: Clarify Schema type Deprecated field usage Reference: https://github.com/hashicorp/terraform-plugin-sdk/issues/1012 --- helper/schema/schema.go | 31 ++++++++++++++++--- .../plugin/sdkv2/schemas/schema-methods.mdx | 13 +++++++- 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/helper/schema/schema.go b/helper/schema/schema.go index 7cbd5858917..b4a95d07530 100644 --- a/helper/schema/schema.go +++ b/helper/schema/schema.go @@ -311,11 +311,32 @@ type Schema struct { // "parent_block_name.0.child_attribute_name". RequiredWith []string - // Deprecated indicates the message to include in a warning diagnostic to - // practitioners when this attribute is configured. Typically this is used - // to signal that this attribute will be removed in the future and provide - // next steps to the practitioner, such as using a different attribute, - // different resource, or if it should just be removed. + // Deprecated defines warning diagnostic details to display to + // practitioners configuring this attribute or block. The warning + // diagnostic summary is automatically set to "Argument is 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 value. It cannot detect practitioner + // configuration values that are unknown ("known after apply"). + // + // 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: + // + // https://github.com/hashicorp/terraform/issues/7569 + // + // Set this field to a practitioner actionable message such as: + // + // - "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." + // Deprecated string // ValidateFunc allows individual fields to define arbitrary validation diff --git a/website/docs/plugin/sdkv2/schemas/schema-methods.mdx b/website/docs/plugin/sdkv2/schemas/schema-methods.mdx index 8b21ba83bf2..f2c47dccf09 100644 --- a/website/docs/plugin/sdkv2/schemas/schema-methods.mdx +++ b/website/docs/plugin/sdkv2/schemas/schema-methods.mdx @@ -132,11 +132,22 @@ ComputedWhen []string // key. ConflictsWith []string -// When Deprecated is set, this attribute is deprecated. +// When Deprecated is set, this attribute is deprecated and a warning +// diagnostic will automatically be raised when it is configured. // // A deprecated field still works, but will probably stop working in near // future. This string is the message shown to the user with instructions on // how to address the deprecation. +// +// This warning diagnostic is only displayed during Terraform's validation +// phase when the attribute is Required or Optional and if the practitioner +// configuration attempts to set the attribute value to a known value. It +// cannot detect practitioner configuration values that are unknown ("known +// after apply"). +// +// 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. Deprecated string // When Removed is set, this attribute has been removed from the schema