For over a year now, provider acceptance testing functionality has been forked into the separate terraform-plugin-testing Go module with its own website documentation. In there is a migration guide, that mainly is about updating import statements to point at the new Go module. There is a lot of value add functionality only being added in the new Go module, such as Terraform version checks, plan checks, not requiring id attribute, etc. but developers might not be aware at all of the new Go module because nothing has ever prompted them in that direction (release notes, Go documentation deprecation comments, etc.).
The original plan was to deprecate the entire terraform-plugin-sdk Go module at once, but that decision has been repeatedly deferred for other priorities. Deprecating the acceptance testing functionality is a much smaller ask.
Proposal
Add Go documentation Deprecated: comments for all helper/resource package functionality that points developers at the newer terraform-plugin-testing Go module.
For example:
// ... existing Go docs ...
//
// Deprecated: Use the equivalent terraform-plugin-testing Go module helper/resource.XXX instead. Refer to the [migration guide] for additional information.
//
// [migration guide]: https://developer.hashicorp.com/terraform/plugin/testing/migrating
In the website documentation, ensure all pages in the testing section include callouts that mention the new Go module and the migration guide.
SDK version
Use-cases
For over a year now, provider acceptance testing functionality has been forked into the separate terraform-plugin-testing Go module with its own website documentation. In there is a migration guide, that mainly is about updating import statements to point at the new Go module. There is a lot of value add functionality only being added in the new Go module, such as Terraform version checks, plan checks, not requiring
idattribute, etc. but developers might not be aware at all of the new Go module because nothing has ever prompted them in that direction (release notes, Go documentation deprecation comments, etc.).The original plan was to deprecate the entire terraform-plugin-sdk Go module at once, but that decision has been repeatedly deferred for other priorities. Deprecating the acceptance testing functionality is a much smaller ask.
Proposal
Add Go documentation
Deprecated:comments for allhelper/resourcepackage functionality that points developers at the newer terraform-plugin-testing Go module.For example:
In the website documentation, ensure all pages in the testing section include callouts that mention the new Go module and the migration guide.