Adding docs for migrating from SDKv2 to the Framework

[bendbennett]

Closes: #459

[robin-norwood]

It's almost there! A few small things to fix.

[bflad]

If you get a chance, you can try running markdownlint CLI against these files to catch things like this:

Suggested change

	## SDKv2
	## SDKv2

And further down with additional newlines after code fences. 👍

[bendbennett]

Have installed and run markdownlint --disable MD013 -- ./website/docs/plugin/framework/migrating/*.

I'm ignoring the MD013/line-length Line length notifications.

In terms of the remaining notifications, I'm interested to hear feedback from @robin-norwood and @laurapacilio as I thought this was intentional but happy to fix however suits:

markdownlint --disable MD013 -- ./website/docs/plugin/framework/migrating/*
./website/docs/plugin/framework/migrating/data-sources.mdx:107 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### SDKv2"]
./website/docs/plugin/framework/migrating/data-sources.mdx:140 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Framework"]
./website/docs/plugin/framework/migrating/provider.mdx:111 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### SDKv2"]
./website/docs/plugin/framework/migrating/provider.mdx:138 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Framework"]
./website/docs/plugin/framework/migrating/provider.mdx:208 MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading [Context: "SDKv2"]
./website/docs/plugin/framework/migrating/provider.mdx:233 MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading [Context: "Framework"]
./website/docs/plugin/framework/migrating/provider.mdx:278 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### SDKv2"]
./website/docs/plugin/framework/migrating/provider.mdx:293 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Framework"]
./website/docs/plugin/framework/migrating/provider.mdx:313 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Migration Notes"]
./website/docs/plugin/framework/migrating/provider.mdx:321 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Example"]
./website/docs/plugin/framework/migrating/provider.mdx:335 MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading [Context: "SDKv2"]
./website/docs/plugin/framework/migrating/provider.mdx:358 MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading [Context: "Framework"]
./website/docs/plugin/framework/migrating/testing.mdx:109 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Example"]
./website/docs/plugin/framework/migrating/testing.mdx:119 MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading [Context: "SDKv2"]
./website/docs/plugin/framework/migrating/testing.mdx:146 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Framework"]

[laurapacilio]

Forgive me - is the problem that we have duplicate headings? My opinion is that they are needed here, but let me know if you disagree!

[bendbennett]

The 2 things that are being flagged by the linter are:

• Duplicate headings (e.g., where we have ### SDKv2 multiple times).
• Emphasis used instead of heading (e.g., SDKv2) rather than #### SDKv2, such as in the ### Example sections.

[bendbennett]

Following the removal of **SDKv2** and **Framework**, we now have the following:

terraform-plugin-framework % markdownlint --disable MD013 -- ./website/docs/plugin/framework/migrating/*
./website/docs/plugin/framework/migrating/testing.mdx:108 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Example"]
./website/docs/plugin/framework/migrating/testing.mdx:118 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "#### SDKv2"]
./website/docs/plugin/framework/migrating/testing.mdx:144 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "#### Framework"]

[bflad]

Since this is showing a "predefined" validator, should we get an example using a custom validation function already? e.g. here's some examples from the AWS provider

https://github.com/hashicorp/terraform-provider-aws/blob/main/internal/service/rds/validate.go

[bflad]

I believe this also closes:

• Provide an upgrade path for SDKv2 providers #158
• Investigate and Determine Computed-Only Block Behavior #214
• Document upgrade path for blocks #281

[robin-norwood]

Do state upgraders "help users migrate resources" or do they do it automatically?

[bendbennett]

Good point. Have reworded as:

You can create state upgraders to automatically migrate resources provisioned with old schema configurations.

[robin-norwood]

Did the testing/provider-factories page not get migrated? I don't see it in the PR. (Also should testing.mdx be testing/index.mdx? @laurapacilio

[bendbennett]

Provider Factories are included within the testing.mdx page. I've update the link.

Let me know about testing.mdx => /testing/index.mdx`.

[github-actions]

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.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.