Document how to write and use sweepers in contributor docs

[melinath]

What kind of contribution is this issue about?

Other (specify in details)

Details

We should document how to write and use sweepers. Currently we have https://github.com/hashicorp/terraform-provider-google/wiki/Developer-Best-Practices#sweepers but that's not accessible to users.

This may make sense to do as part of a broader effort to make sweepers more accessible to users, for example by making them configurable.

References

#16859
#17835
yaqs/6453048037068505088

[SarahFrench]

Data point for this issue: GoogleCloudPlatform/magic-modules#11413 (comment)

[melinath]

Hashicorp's documentation about sweepers: https://developer.hashicorp.com/terraform/plugin/sdkv2/testing/acceptance-tests/sweepers

[SarahFrench]

This information in the old CONTRIBUTING.md for TPG will be useful for this issue:

Running provider tests often can lead to dangling test resources caused by test failures. Terraform has a capability to run Sweepers which can go through and delete resources. In TPG, sweepers mainly:

1. List every resource in a project of a specific kind
2. Iterate through the list and determine if a resource is sweepable
3. If sweepable, delete the resource

Sweepers run by using the -sweep and -sweep-run TESTARGS flags:

TF_LOG=TRACE make testacc TEST=./google TESTARGS='-sweep=us-central1 -sweep-run=<sweeper-name-here>' > output.log

[SarahFrench]

Some more information:

• The sweeper name is the string used to register the sweeper in the provider, e.g. here the name is "ComputeDisk". This is the value used for -sweep-run=<sweeper-name-here> above
• The -sweep flag determines which value is passed through as the region string argument to the sweeper function (see here)
• The 'entrypoint' for sweepers is the sweeper package, and individual sweepers from other packages are registered there using sweeper.AddTestSweepers

[SarahFrench]

Here's an example of where some docs about sweepers would be helpful: #19983 (comment)

[owenhuyn]

It looks like another PR #12334 would have been helpful to have sweepers documented since there was some engineering friction with the review.