Document the default behavior of --tf-version and usage of Terraform binary

[austinvalle]

Closes #323

Not sure if we also want to make an official recommendation on using the latest version of Terraform for generating the docs?

[bflad]

Excellent! 🚀

Not sure if we also want to make an official recommendation on using the latest version of Terraform for generating the docs?

I would say yes to recommending latest! For a few reasons:

1. Simplicity
2. Terraform 1.8 will be required for functions documentation
3. This is a developer-side workflow needing Terraform, so it shouldn't be too much of a burden to use latest (rather than practitioner environments that typically need to be audited for Terraform version updates)

[andreaangiolillo]

@austinvalle @bflad Could you update the logic to print a warning message if the local TF version is not the latest?

[bflad]

@andreaangiolillo thank you for the additional consideration here. I would suggest opening a feature request with what you would expect to occur and we can decide/prioritize as with any other feature request.

Discussed in #286, there is the potential that tfplugindocs may call terraform version -json to detect that problematic situation. That output also contains an terraform_outdated boolean property which could be used for what you are proposing, however there are some important considerations:

• That information is populated when Terraform automatically calls the Checkpoint service to determine if the version is the latest. Environments may have restrictive egress policies where they might want/need to disable the check, defeating the detection capability. It may also make sense to disable it for performance or to prevent unrelated Checkpoint errors from occurring at all, which is what we do in terraform-plugin-testing, for example.
• There is a chance with having too many warnings becoming noise for developers. Being on the non-latest version, especially when only behind on patch version, will generally not cause any real issues. It would be preferable to avoid false positives and only raise warnings/errors if there is a known problem. Without that, developers may then want the ability to disable or conditionalize the warning. All of these make the implementation more complex than it might seem on the surface.

All this is likely good to discuss in a feature request though, rather than this closed pull request. Thank you. 👍

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.