hashicorp · austinvalle · Mar 17, 2023 · Mar 9, 2023 · Mar 9, 2023 · Mar 9, 2023
@@ -125,7 +125,7 @@ Dependency management is performed by [dependabot](https://docs.github.com/en/co
 HashiCorp’s open-source projects have always maintained user-friendly, readable CHANGELOGs that allow practitioners and developers to tell at a glance whether a release should have any effect on them, and to gauge the risk of an upgrade.
 
 We follow Terraform Plugin
-[changelog specifications](https://www.terraform.io/plugin/sdkv2/best-practices/versioning#changelog-specification).
+[changelog specifications](https://developer.hashicorp.com/terraform/plugin/best-practices/versioning#changelog-specification).
 
 #### Changie Automation Tool
 This project uses the [Changie](https://changie.dev/) automation tool for changelog automation.
@@ -136,7 +136,7 @@ After Changie is installed on your local machine, run:
 ```bash
 changie new
 ```
-and choose a `kind` of change corresponding to the Terraform Plugin [changelog categories](https://developer.hashicorp.com/terraform/plugin/sdkv2/best-practices/versioning#categorization)
+and choose a `kind` of change corresponding to the Terraform Plugin [changelog categories](https://developer.hashicorp.com/terraform/plugin/best-practices/versioning#categorization)
 
 Fill out the body field following the entry format. Changie will then prompt for a Github issue or pull request number.
 

@@ -113,37 +113,13 @@
     "title": "Best Practices",
     "routes": [
       { "title": "Overview", "path": "best-practices" },
-      {
-        "title": "Naming",
-        "path": "best-practices/naming"
-      },
-      {
-        "title": "Depending on Providers",
-        "path": "best-practices/depending-on-providers"
-      },
       {
         "title": "Deprecations, Removals, and Renames",
         "path": "best-practices/deprecations"
       },
       {
         "title": "Detecting Drift",
         "path": "best-practices/detecting-drift"
-      },
-      {
-        "title": "Handling Sensitive Data",
-        "path": "best-practices/sensitive-state"
-      },
-      {
-        "title": "Testing Patterns",
-        "path": "best-practices/testing"
-      },
-      {
-        "title": "Versioning and Changelog",
-        "path": "best-practices/versioning"
-      },
-      {
-        "title": "Writing Non-Go Providers",
-        "path": "best-practices/other-languages"
       }
     ]
   }

@@ -1,13 +1,13 @@
 ---
-page_title: 'Plugin Development - Deprecations, Removals, and Renames Best Practices'
+page_title: 'Plugin Development - SDKv2 Deprecations, Removals, and Renames Best Practices'
 description: 'Recommendations for deprecations, removals, and renames.'
 ---
 
 # Deprecations, Removals, and Renames
 
 Terraform is trusted for managing many facets of infrastructure across many organizations. Part of that trust is due to consistent versioning guidelines and setting expectations for various levels of upgrades. Ensuring backwards compatibility for all patch and minor releases, potentially in concert with any upcoming major changes, is recommended and supported by the Terraform development framework. This allows operators to iteratively update their Terraform configurations rather than require massive refactoring.
 
-This guide is designed to walk through various scenarios where existing Terraform functionality requires future removal, while maintaining backwards compatibility. Further information about the versioning terminology (e.g. `MAJOR`.`MINOR`.`PATCH`) in this guide can be found in [the versioning guidelines documentation](/terraform/plugin/sdkv2/best-practices/versioning).
+This guide is designed to walk through various scenarios where existing Terraform functionality requires future removal, while maintaining backwards compatibility. Further information about the versioning terminology (e.g. `MAJOR`.`MINOR`.`PATCH`) in this guide can be found in [the versioning guidelines documentation](/terraform/plugin/best-practices/versioning).
 
 ~> **NOTE:** Removals should only ever occur in `MAJOR` version upgrades.
 
@@ -682,7 +682,7 @@ The recommended process is as follows:
 1. Add `DeprecatedMessage` to the schema definition of the existing (now the "old") resource, noting to use the new resource in the message.
 1. Add `!> **WARNING:** This resource is deprecated and will be removed in the next major version` to the documentation of the existing (now the "old") resource, noting to use the new resource.
 1. Add the new resource to the provider `ResourcesMap`
-1. Follow the rest of the procedures in the [Provider Attribute Removal section](#provider-attribute-removal).
+1. Follow the rest of the procedures in the [Provider Data Source or Resource Removal section](#provider-data-source-or-resource-removal).
 
 ### Example Resource Renaming
 
@@ -708,7 +708,7 @@ func resourceExampleExistingWidget() *schema.Resource {
 }
 ```
 
-In order to support renaming `example_existing_widget` to `example_new_widget`, this sample can be written as the following to support both attributes simultaneously until the `existing_attribute` is removed:
+In order to support renaming `example_existing_widget` to `example_new_widget`, this sample can be written as the following to support both resources simultaneously until the `example_existing_widget` resource is removed:
 
 ```go
 func Provider() terraform.ResourceProvider {

@@ -1,5 +1,5 @@
 ---
-page_title: Plugin Development - Detecting Drift
+page_title: Plugin Development - SDKv2 Detecting Drift
 description: |-
   "Drift" describes changes to infrastructure outside of Terraform. Learn how
   to ensure that Terraform detects drift so that users will know when their

@@ -1,11 +1,16 @@
 ---
-page_title: Plugin Development - Best Practices
+page_title: Plugin Development - SDKv2 Best Practices
 description: >-
-  Patterns that ensure a consistent user experience, including naming,
-  deprecation, beta features, testing, and versioning.
+  Patterns that ensure a consistent user experience, including deprecation, beta features, and detecting drift.
 ---
 
-# Terraform Plugin Best Practices
+<Highlight>
+
+This best practices section only contains guidance for plugins built with [Terraform Plugin SDK](/terraform/plugin/sdkv2). More generic best practices that apply to both SDK and [Terraform Plugin Framework](/terraform/plugin/framework) can be found in the [Plugin Development Best Practices](/terraform/plugin/best-practices) section.
+
+</Highlight>
+
+# Terraform SDKv2 Best Practices
 
 A key feature of Terraform is its plugin system, which separates the details of
 specific vendor APIs from the shared logic for managing state, managing configuration,
@@ -15,16 +20,7 @@ specific cloud provider, allowing each provider to fully support its unique
 resources and lifecycles and not settling for the lowest common denominator
 across all provider resources of that type (virtual machines, networks,
 configuration management systems, et. al). While each provider is unique, over
-the years, we accumulated recommended patterns that help ensure a consistent user experience when using Terraform for any given provider. This page describes best practices that generally apply to most
-Providers, with a brief description of each, and link to read more. 
-
-This section is a work in progress, with more sections to come.
-
-## Naming
-
-[Naming][naming] resources, data sources, and attributes in plugins is how plugin authors
-expose their functionality to operators and using patterns common to other plugins
-lays the foundation for a good user experience.
+the years, we accumulated recommended patterns that help ensure a consistent user experience when using Terraform for any given provider. This page describes best practices that generally apply to most Providers built with the legacy SDK, with a brief description of each, and link to read more. 
 
 ## Deprecations, Removals, and Renames
 
@@ -53,30 +49,6 @@ Drift][drift], we cover some best practices to ensure Terraform's statefile is
 an accurate reflection of reality, to provide accurate plan and apply
 functionality.
 
-## Testing Patterns
-
-Terraform developers are encouraged to write acceptance tests that create real
-resource to verify the behavior of plugins, ensuring a reliable and safe
-way to manage infrastructure. In [Testing Patterns][testing-patterns] we cover
-some basic acceptance tests that almost all resources should have to validate
-not only the functionality of the resource, but that the resource behaves as
-Terraform would expect.
-
-## Versioning and Changelog
-
-Terraform development serves two distinct audiences: those writing plugin code
-and those implementing them. By clearly and consistently allowing operators to
-easily understand changes in plugin implementation via version numbering and
-documenting those changes, a trust is formed between the two audiences. In
-[Versioning and Changelog][versioning] we cover some guidelines when deciding
-release versions and how to relay changes through documentation.
-
-[naming]: /terraform/plugin/sdkv2/best-practices/naming
-
 [deprecations]: /terraform/plugin/sdkv2/best-practices/deprecations
 
 [drift]: /terraform/plugin/sdkv2/best-practices/detecting-drift
-
-[testing-patterns]: /terraform/plugin/sdkv2/best-practices/testing
-
-[versioning]: /terraform/plugin/sdkv2/best-practices/versioning