docs missing deprecation notice and migration steps

[matifali]

Provider docs at registry.coder.com do not mention the deprecation of parameters.

For example, multiple fields of data.coder_workspace were deprecated in v0.23.0, but the docs at https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/workspace do not indicate any such information.

Additionally, when a resource is deprecated, the message should contain the new resource to be migrated to or a link to some migration guide both in Terraform logs and on the docs page.

[matifali]

related #203

[johnstcn]

Looks like you need to specify DeprecationMessage and not just Deprecated.
https://developer.hashicorp.com/terraform/plugin/framework/handling-data/schemas#deprecationmessage-1

[mtojek]

@johnstcn DeprecationMessage is available only for entire Resources, here we want to deprecate a few properties.

I will check if there is an option to customize the template and include the deprecation message in Markdown files.

[mtojek]

Ok, I researched the issue. It may not be a straightforward solution or, in other words, it could be easier to apply patch .md files.

The docs generator strongly depends on providers schema:

... and the schema does not expose the deprecation message.

It would be hard/impossible to expose the message via the fork&modify approach, so my recommendation is to implement a script which will run after the hashicorp generator, and "patch" docs:

- `owner_email` (String, Deprecated) Email address of the workspace owner.

->

- `owner_email` (String, Deprecated: Use `coder_workspace_owner.email` instead.) Email address of the workspace owner.

@johnstcn @stirby Please let me know your thoughts 👍

[johnstcn]

Thanks for investigating! I think that's a perfectly valid workaround.