provider development improvements

[drewmullen]

for provider development you want to include directions for:

• what kinds of acc tests are expected. i always reference the aws contrib guide: https://hashicorp.github.io/terraform-provider-aws/running-and-writing-acceptance-tests/
• writing docs using the doc generator plugin
• that you should usually create a singular and plural data source for most resources
• that changelog entries should be included based on the norms of the provider or an opinion inserted by this repo

[drewmullen]

docs:

• no outputs in examples,
• no provider or terraform blocks in examples
• each example should be in its own file and imported to the template for readability

[drewmullen]

add docs on writing ephemeral resources

[drewmullen]

although SDK can be mixed with framework, always prefer framework. ask before adding anything in that is SDK

[bbasata]

although SDK can be mixed with framework, always prefer framework. ask before adding anything in that is SDK

To build on this:

Existing provider: use the presence of the terraform-plugin-mux Go module dependency to "detect" whether to use Framework-only, SDKv2-only, or Framework+SDKv2.

For new providers, Framework by default.

[ffalor]

I haven't used Claude skills yet so not sure if this makes sense or not, but could this be split into two different ones?

The sdkv2 stuff would just be noise for new providers that only use framework. The same is true for sdkv2 providers that still do not use framework.

[bbasata]

I haven't used Claude skills yet so not sure if this makes sense or not, but could this be split into two different ones?

Very likely, yes. Two skills, each with a clear description of its use, so that one skill or the other is activated in the right context.

[bbasata]

What if: a setup-tools skill: in-repo configuration (or re-configuration) for optional tools that are useful for provider development:

• Static analysis (golangci-lint, Semgrep CE, …)

• Provider publishing (GoReleaser)

• Changelogs (Changie)

Cross-reference:

• new-terraform-provider skill – deliberately minimal
• terraform-provider-scaffolding-framework – makes more default choices

[ffalor]

I was reading the skill-creator claude skill.

It looks like we could do something like this:

/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── SDKv2.md
    └── plugin-framework.md 

SKILL.md will help determine which extra context to load.

This is for Claude Code skills. I'm not sure if the other tools out there support this.

[AdamTylerLynch]

A set of open PRs now covers most of this issue — mapping each ask to where it landed:

• Expected acceptance tests (the AWS contrib guide's coverage: _basic + import step, _disappears, per-attribute): PR provider-resources: replace AWS-internal patterns with generic Plugin Framework guidance #79 states this as required coverage in provider-resources, distilled from that same guide.
• Docs via the doc generator: PR provider-resources: replace AWS-internal patterns with generic Plugin Framework guidance #79 makes tfplugindocs the canonical path in provider-resources; PR provider-docs: add action documentation guidance #84 extends provider-docs with action pages and (per the comments here) the example-file conventions — one example per file in examples/ imported via tffile, no terraform/provider/output blocks in examples.
• Singular and plural data sources for most resources: PR provider-resources: replace AWS-internal patterns with generic Plugin Framework guidance #79's design-principles reference now recommends shipping both, with the error-semantics contract for each.
• Changelog entries per repo norms: PRs provider-resources: replace AWS-internal patterns with generic Plugin Framework guidance #79/provider-actions: generalize AWS-specific patterns and align test protocol #80 add "changelog entry if the repo tracks release notes" checklist items rather than mandating one convention.
• Framework-first / SDKv2 separation (@drewmullen, @bbasata, @ffalor): PR provider-resources: replace AWS-internal patterns with generic Plugin Framework guidance #79 removes the SDKv2 example code from provider-resources and states the Framework-required-for-net-new policy up front, including @bbasata's terraform-plugin-mux-in-go.mod detection heuristic. The SDKv2 content now lives only in a dedicated provider-framework-migration skill (PR feat: add provider-framework-migration skill for SDKv2 to Framework migration #86), so it stops being noise in new-provider contexts — effectively the two-skill split discussed here.
• Ephemeral resources (@drewmullen): PR feat: add provider-ephemeral-resources skill #87 adds a dedicated provider-ephemeral-resources skill (Open/Renew/Close lifecycle, registration, echo-provider testing pointer).

Still open from this thread: @bbasata's setup-tools skill idea (golangci-lint/GoReleaser/Changie bootstrapping) — not covered by any of the above.