website: Add data consistency error migration docs for "planned value does not match config value" (#831)

* move docs from sdk PR

* Update website/docs/plugin/framework/migrating/resources/crud.mdx

Co-authored-by: Brian Flad <[email protected]>

* removed state example

---------

Co-authored-by: Brian Flad <[email protected]>

Author: austinvalle

website/docs/plugin/framework/migrating/index.mdx

@@ -36,7 +36,7 @@ As you complete the migration, we recommend that you follow Test Driven Developm
 Take the following steps when you migrate a provider from SDKv2 to the Framework:
 
 - Ensure all [tests](/terraform/plugin/framework/migrating/testing#testing-migration) pass.
-- Consider [finding SDKv2 resource data consistency errors](/terraform/plugin/sdkv2/resources/data-consistency-errors), which might affect migrating to the Framework. Some errors can be resolved and verified with SDKv2 code before migration, if desired, otherwise resolving these errors must be part of the migration.
+- Consider [finding SDKv2 resource data consistency errors](/terraform/plugin/sdkv2/resources/data-consistency-errors), which might affect migrating to the Framework. Some errors can be resolved and verified with SDKv2 code before migration, if desired, otherwise resolving these errors must be [part of the migration](/terraform/plugin/framework/migrating/resources/crud#resolving-data-consistency-errors).
 - [Serve the provider](/terraform/plugin/framework/migrating/providers#serving-the-provider) via the Framework.
   - Implement [muxing](/terraform/plugin/framework/migrating/mux), if you plan to migrate the provider iteratively.
 - Update the [provider definition](/terraform/plugin/framework/migrating/providers#provider-definition) to use the Framework.

website/docs/plugin/framework/migrating/resources/crud.mdx

@@ -73,7 +73,7 @@ function. In the Framework, you must implement each of the CRUD lifecycle functi
 `schema.ResourceData`. In the Framework, you get attribute values from the configuration and plan by accessing
 `Config` and `Plan` on `resource.CreateRequest`. You set attribute values in Terraform's state by mutating `State`
 on `resource.CreateResponse`.
-- In SDKv2, certain resource schema definition and data consistency errors are only visible as Terraform warning logs by default. After migration, these errors will always be visible to practitioners and prevent further Terraform operations. The [SDKv2 resource data consistency errors documentation](/terraform/plugin/sdkv2/resources/data-consistency-errors) discusses how to find and potentially resolve these.
+- In SDKv2, certain resource schema definition and data consistency errors are only visible as Terraform warning logs by default. After migration, these errors will always be visible to practitioners and prevent further Terraform operations. The [SDKv2 resource data consistency errors documentation](/terraform/plugin/sdkv2/resources/data-consistency-errors) discusses how to find these errors in SDKv2 resources and potential solutions **prior** to migrating. See the [Resolving Data Consistency Errors](#resolving-data-consistency-errors) section for Plugin Framework solutions **during** migration.
 
 ## Example
 
@@ -126,3 +126,133 @@ func (r *exampleResource) Create(ctx context.Context, req resource.CreateRequest
     resp.Diagnostics.Append(diags...)
 }
 ```
+
+## Resolving Data Consistency Errors
+<Note>
+
+See the [SDKv2 data consistency errors documentation](/terraform/plugin/sdkv2/resources/data-consistency-errors) for background info, debugging tips, and potential SDKv2 solutions.
+
+</Note>
+
+### Planned Value does not match Config Value
+
+If an SDKv2 resource is raising this type of error or [warning log](/terraform/plugin/sdkv2/resources/data-consistency-errors#checking-for-warning-logs):
+
+```text
+TIMESTAMP [WARN]  Provider "TYPE" produced an invalid plan for ADDRESS, but we are tolerating it because it is using the legacy plugin SDK.
+    The following problems may be the cause of any confusing errors from downstream operations:
+      - .ATTRIBUTE: planned value cty.StringVal("VALUE") does not match config value cty.StringVal("value")
+```
+
+This occurs for attribute schema definitions that are `Optional: true` and `Computed: true`; where the planned value, returned by the provider, does not match the attribute's config value or prior state value. For example, value's for an attribute of type string must match byte-for-byte.
+
+An example root cause of this issue could be from API normalization, such as a JSON string being returned from an API and stored in state with differing whitespace then what was originally in config.
+
+#### SDKv2 Example
+
+Here is an example of an SDKv2 resource schema and terraform config that simulates this data consistency error:
+
+```go
+func thingResource() *schema.Resource {
+	return &schema.Resource{
+		// ...
+		Schema: map[string]*schema.Schema{
+			"word": {
+				Type:     schema.TypeString,
+				Optional: true,
+				Computed: true,
+				StateFunc: func(word interface{}) string {
+                    // This simulates an API returning the 'word' attribute as all uppercase,
+                    // which is stored to state even if it doesn't match the config or prior value.
+					return strings.ToUpper(word.(string))
+				},
+			},
+		},
+	}
+}
+```
+
+```hcl
+resource "examplecloud_thing" "this" {
+  word = "value"
+}
+```
+
+A [warning log](/terraform/plugin/sdkv2/resources/data-consistency-errors#checking-for-warning-logs) will be produced and the resulting state after applying a new resource will be `VALUE` instead of `value`.
+
+#### Migrating to Plugin Framework
+
+When a resource with this behavior and prior state is migrated to Plugin Framework, depending on the business logic, you could potentially see:
+
+- Resource drift in the plan; Terraform will always detect a change between the config and state value. If no [modification](/terraform/plugin/framework/resources/plan-modification) is implemented, you could see drift in the plan:
+```hcl
+resource "examplecloud_thing" "this" {
+  word = "value"
+}
+```
+```text
+examplecloud_thing.this: Refreshing state...
+
+Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
+  ~ update in-place
+
+Terraform will perform the following actions:
+
+  # examplecloud_thing.this will be updated in-place
+  ~ resource "examplecloud_thing" "this" {
+      ~ word = "VALUE" -> "value"
+    }
+
+Plan: 0 to add, 1 to change, 0 to destroy.
+```
+- If you mimic the original SDKv2 behavior of storing a different value from config/prior value into state in the `Update` method, you will see an error like below:
+```text
+examplecloud_thing.this: Modifying...
+╷
+│ Error: Provider produced inconsistent result after apply
+│ 
+│ When applying changes to examplecloud_thing.this, provider "provider[\"TYPE\"]" produced an unexpected
+│ new value: .word: was cty.StringVal("value"), but now cty.StringVal("VALUE").
+│ 
+│ This is a bug in the provider, which should be reported in the provider's own issue tracker.
+```
+
+#### Recommended Solution
+To solve this issue, the provider code must preserve the config value or prior state value when producing the new state. The recommended way to implement this logic is by creating a [custom type](/terraform/plugin/framework/handling-data/types/custom) with [semantic equality logic](/terraform/plugin/framework/handling-data/types/custom#semantic-equality). A custom type can be shared across multiple resource attributes and will ensure that the semantic equality logic is invoked during the `Read`, `Create`, and `Update` methods respectively.
+
+For the above example, the semantic equality implementation below would resolve the resource drift and error:
+
+<Tip>
+
+The example code below is a partial implementation of a custom type, please see the [Custom Value Type documentation](/terraform/plugin/framework/handling-data/types/custom#value-type) for guidance.  
+
+</Tip>
+
+```go
+type CaseInsensitive struct {
+	basetypes.StringValue
+}
+
+// ... custom value type implementation
+
+// StringSemanticEquals returns true if the given string value is semantically equal to the current string value. (case-insensitive)
+func (v CaseInsensitive) StringSemanticEquals(_ context.Context, newValuable basetypes.StringValuable) (bool, diag.Diagnostics) {
+	var diags diag.Diagnostics
+
+	newValue, ok := newValuable.(CaseInsensitive)
+	if !ok {
+		diags.AddError(
+			"Semantic Equality Check Error",
+			"An unexpected value type was received while performing semantic equality checks. "+
+				"Please report this to the provider developers.\n\n"+
+				"Expected Value Type: "+fmt.Sprintf("%T", v)+"\n"+
+				"Got Value Type: "+fmt.Sprintf("%T", newValuable),
+		)
+
+		return false, diags
+	}
+
+    return strings.EqualFold(newValue.ValueString(), v.ValueString()), diags
+}
+```
+

website/docs/plugin/framework/migrating/resources/index.mdx

@@ -141,7 +141,7 @@ the `resource.Resource` interface, which includes a `Schema` method that returns
 - SDKv2 implements a resource's CRUD operations as functions on the `schema.Resource`. In the Framework, you define a
 type that implements the `resource.Resource` interface. The resource interface contains the functions that define your resource's
 CRUD operations.
-- SDKv2 by default demotes certain resource schema definition and data consistency errors to only be visible as Terraform warning logs. After migration, these errors will always be visible to practitioners and prevent further Terraform operations. The [SDKv2 resource data consistency errors documentation](/terraform/plugin/sdkv2/resources/data-consistency-errors) discusses how to find and potentially resolve these.
+- SDKv2 by default demotes certain resource schema definition and data consistency errors to only be visible as Terraform warning logs. After migration, these errors will always be visible to practitioners and prevent further Terraform operations. The [SDKv2 resource data consistency errors documentation](/terraform/plugin/sdkv2/resources/data-consistency-errors) discusses how to find these errors in SDKv2 resources and potential solutions **prior** to migrating. See the [CRUD - Resolving Data Consistency Errors](/terraform/plugin/framework/migrating/resources/crud#resolving-data-consistency-errors) section for Plugin Framework solutions **during** migration.
 
 ## Example