Migrate Non-SDK Specific Best Practices Documentation #1151
Description
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/websiteGit 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 |