Migrate Non-SDK Specific Best Practices Documentation

[bflad]

Description

Now that terraform-plugin-framework is generally available and terraform-plugin-testing is released, we can expect that over time the traffic to the terraform-plugin-sdk website documentation (Terraform > Plugin Development > SDKv2) will begin to lessen. Inside the SDK website documentation is a "Best Practices" section which captures helpful information and consistency tips from the ecosystem over time. These pages are briefly described below.

Page	Description
Overview	Index page for others.
Naming	Generic Resource, Data Source, and Attribute naming recommendations.
Depending on Providers	Interfacing to Terraform Providers is expected to be Terraform CLI or gRPC, not Go code itself.
Deprecations, Removals, and Renames	Semi-SDK specific information for how to handle breaking change situations in providers.
Detecting Drift	Capture all state during refresh, update state after modification (unfortunately risky half-pattern), and SDK-specific error checking/helpers.
Handling Sensitive Data	Use Sensitive attribute behavior, don't encrypt attribute values manually.
Testing Patterns	Generic information about the provider testing framework, examples of common use case tests.
Versioning and Changelog	Generic provider versioning and consistent changelog formatting.
Writing Non-Go Providers	Policy and reasoning around HashiCorp only supporting the Go language at this time.

There is quite a bit of this information which is not specific to terraform-plugin-sdk, so it might make sense to migrate some of the content to other repositories, which hold other sections of the website content.

Proposal

In general, the steps for each page will be:

• In the target repository, copy/migrate the new mdx content and ensure its deployed in production (either by product release or special release/website Git tag updates)
• In terraform-website, introduce a redirect for the old URL path to the new URL page.
• In terraform-plugin-sdk, update the side navigation to href the new page.
• In terraform-plugin-sdk, remove the old mdx content

The proposed migration strategy for each page is:

Page	Target Repository	Target Navigation
Overview	Each repository as necessary	e.g. Plugin Development > Best Practices > Overview
Naming	terraform-docs-common	Plugin Development > Best Practices > Naming
Depending on Providers	terraform-docs-common	Plugin Development > Best Practices > Interacting with Providers
(SPLIT) Deprecations, Removals, and Renames	terraform-plugin-sdk	SDKv2 > Deprecations, Removals, and Renames
(SPLIT) Deprecations, Removals, and Renames	terraform-plugin-framework	Framework > Deprecations, Removals, and Renames
Detecting Drift	TBD (terraform-plugin-framework?)	TBD (may already be covered by Framework > Resources > Read?)
Handling Sensitive Data	terraform-docs-common	Plugin Development > Best Practices > Handling Sensitive Data
Testing Patterns	terraform-plugin-testing	Testing > Acceptance Testing > Patterns
Versioning and Changelog	terraform-docs-common	Plugin Development > Best Practices > Versioning and Changelog
Writing Non-Go Providers	terraform-docs-common	Plugin Development > Best Practices > Provider Code Language

References

• website: Add highlight callout for migrating to terraform-plugin-testing #1150

[austinvalle]

All PRs are open and ready for review, order of releases should be:

1. terraform-docs-common should merge/deploy first (only adds new pages/navigation)
2. terraform-website should merge/deploy next (redirect dependent on new pages added in step 1)
3. terraform-plugin-framework should be next (new pages, relies on links from pages added in step 1)
4. terraform-plugin-sdk last (deletes duplicate pages + removes pages in sidebar)

[austinvalle]

• terraform-docs-common changes have been deployed 🚀

• terraform-plugin-sdk removals are merged to main, will be deployed with next release

• terraform-website has the redirects in-place

• Add deprecation documentation (from Best Practices - SDKv2) terraform-plugin-framework#684 still needs to be reviewed + will go with next framework release

[austinvalle]

All done 🚀

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.