Adding the upstream repository as a submodule is not documented

[thatliuser]

What happened?

Hello, I've been working on a Pulumi provider using this template, and I found that the documentation in SETUP didn't provide enough information to get my provider working properly. Specifically, I had to add the Terraform provider as a submodule in the upstream folder and run a go module replace to get the provider to build properly. I modeled my approach on the pulumi-aws provider, which uses the same approach. As far as I can tell, this is a pretty common issue to run into (as Terraform providers do not handle major versions >=1 properly and therefore can't be downloaded with go get). Should this be documented somewhere? I'd be happy to write something about it but I'm a little unclear on the actual mechanism here so it would be nice to get a better explanation.

Example

Clone the repository and follow the SETUP.md for the terraform-provider-formal repository. An error similar to the following should occur when trying to build the provider:

go: github.com/formalco/terraform-provider-formal@v4.17.1+incompatible: verifying go.mod: github.com/formalco/terraform-provider-formal@v4.17.1+incompatible/go.mod: reading https://sum.golang.org/lookup/github.com/formalco/terraform-provider-formal@v4.17.1+incompatible: 404 Not Found
   server response: not found: github.com/formalco/terraform-provider-formal@v4.17.1+incompatible: invalid version: module contains a go.mod file, so module path must match major vers ("github.com/formalco/terraform-provider-formal/v4")

Output of pulumi about

CLI
Version 3.242.0
Go Version go1.26.3
Go Compiler gc

Host
OS darwin
Version 26.5.2
Arch arm64

Environment Variables:
Name Value
PULUMI_HOME "/Users/eric/Documents/pulumi-formal/.pulumi"

Pulumi locates its logs in /var/folders/ry/0_024gqs6tb27bl073bdjr4w0000gn/T/ by default

Additional context

No response

Contributing

Vote on this issue by adding a 👍 reaction.
To contribute a fix for this issue, leave a comment (and link to your pull request, if you've opened one already).

[corymhall]

@thatliuser that does look like a gap in our documentation. It looks like the best place for this documentation might be the README in this repo. We can probably add a section on what to do if your provider matches different patterns not represented by the xyz test provider.