Update dynamic provider docs for new binary name & document the relea…

…se process (#2153)

dynamic/README.md

@@ -1,42 +1,39 @@
 <!-- -*- fill-column: 110 -*- -->
 # Dynamic Bridged Provider
 
-A *dynamically bridged provider* is a Pulumi provider parameterized by the identity of a terraform
-provider. It consists of a binary `pulumi-terraform-bridge`, which is spun up as a provider by `pulumi`. The
+A *dynamically bridged provider* is a Pulumi provider parameterized by the identity of a Terraform
+provider. It consists of a binary `pulumi-terraform-provider`, which is spun up as a provider by `pulumi`. The
 binary is responsible for downloading the terraform provider it is emulating, then translating `pulumi`’s
-[gRPC protocol](https://github.com/pulumi/pulumi/tree/master/proto/pulumi) into [Terraform’s v6
-protocol](https://developer.hashicorp.com/terraform/plugin/terraform-plugin-protocol).
+[gRPC protocol](https://github.com/pulumi/pulumi/tree/master/proto/pulumi) into [Terraform’s v6 protocol](https://developer.hashicorp.com/terraform/plugin/terraform-plugin-protocol).
 
 ## Usage
 
 If you are using a language besides Pulumi YAML, you start by generating an SDK.
 
 ### SDK Generation
 
-SDK generation relies on an existing terraform provider. The Terraform provider can be in a Terraform registry
-(such as [OpenTofu's Registry](https://opentofu.org/docs/internals/provider-registry-protocol/)) or local to
-your machine.
+SDK generation relies on an existing Terraform provider. The Terraform provider can be in a Terraform registry
+(such as [OpenTofu's Registry](https://opentofu.org/docs/internals/provider-registry-protocol/)) or local to your machine.
 
 #### Registry based SDK generation
 
 To generate an SDK based on a Terraform provider in a Terraform Registry, use:
 
 ``` sh
-pulumi package gen-sdk terraform-bridge [hostname/][namespace/]<type> [version] [--language <lang>]
+pulumi package gen-sdk terraform-provider [hostname/][namespace/]<type> [version] [--language <lang>]
 ```
 
-For example, to generate a Typescript SDK for [Azure's Alz
-provider](https://github.com/Azure/terraform-provider-alz) at version v0.11.1, you would run:
+For example, to generate a Typescript SDK for [Azure's Alz provider](https://github.com/Azure/terraform-provider-alz) at version v0.11.1, you would run:
 
 ``` sh
-pulumi package gen-sdk --language typescript terraform-bridge registry.opentofu.org/Azure/alz 0.11.1
+pulumi package gen-sdk --language typescript terraform-provider registry.opentofu.org/Azure/alz 0.11.1
 ```
 
 At the time of writing, the latest version is `v0.11.1`, so you could drop the version:
 
 ``` patch
--pulumi package gen-sdk --language typescript terraform-bridge registry.opentofu.org/Azure/alz 0.11.1
-+pulumi package gen-sdk --language typescript terraform-bridge registry.opentofu.org/Azure/alz
+-pulumi package gen-sdk --language typescript terraform-provider registry.opentofu.org/Azure/alz 0.11.1
++pulumi package gen-sdk --language typescript terraform-provider registry.opentofu.org/Azure/alz
 ```
 
 If no version is specified, then the latest version is used.
@@ -45,8 +42,8 @@ The default registry is `registry.opentofu.org`, so you can omit the registry as
 
 
 ``` patch
--pulumi package gen-sdk --language typescript terraform-bridge registry.opentofu.org/Azure/alz
-+pulumi package gen-sdk --language typescript terraform-bridge Azure/alz
+-pulumi package gen-sdk --language typescript terraform-provider registry.opentofu.org/Azure/alz
++pulumi package gen-sdk --language typescript terraform-provider Azure/alz
 ```
 
 The information you entered (with the registry and the version specified) are embedded in the generated SDK,
@@ -57,22 +54,22 @@ so you won't need to enter any of this information again as long as you use the
 To generate an SDK based on a Terraform provider on your local file system, use:
 
 ``` sh
-pulumi package gen-sdk terraform-bridge [path/]terraform-provider-[name]
+pulumi package gen-sdk terraform-provider [path/]terraform-provider-[name]
 ```
 
 The name of the provider must start with `terraform-provider-`.
 
 ## Architecture
 
-The `pulumi-terraform-bridge` provider works by acquiring and running a Terraform provider, and then acting as
+The `pulumi-terraform-provider` provider works by acquiring and running a Terraform provider, and then acting as
 a translation middleware between the Pulumi engine and the Terraform provider.
 
 A typical usage looks like this:
 
 ``` mermaid
 sequenceDiagram
     participant P as pulumi
-    create participant B as pulumi-terraform-bridge
+    create participant B as pulumi-terraform-provider
     P->>B: Run Pulumi Provider
     P->>B: Parameterize({name: "example", version: "v1.2.3"})
     create participant T as terraform-provider-example
@@ -93,7 +90,7 @@ sequenceDiagram
     B-->>P: Cancel done
 ```
 
-Diving deeper into how the repo is laid out, we see:
+Diving deeper into how the repository is laid out, we see:
 
 ``` console
 ./
@@ -246,3 +243,32 @@ func ReadResourceRequest(i *tfprotov6.ReadResourceRequest) *tfplugin6.ReadResour
 	}
 }
 ```
+## Releasing & [`pulumi/pulumi-terraform-provider`](https://github.com/pulumi/pulumi-terraform-provider)
+
+The `pulumi-terraform-provider` codebase is located in
+[github.com/pulumi/pulumi-terraform-bridge/dynamic](https://github.com/pulumi/pulumi-terraform-bridge/blob/master/dynamic). However, the provider is released from
+[github.com/pulumi/pulumi-terraform-provider](https://github.com/pulumi/pulumi-terraform-provider). There are 2 reasons for this:
+
+1. Pulumi's plugin discovery mechanism assumes that official plugins are located at
+   `github.com/pulumi/pulumi-${PLUGIN_NAME}`. If we want to use the plugin name `terraform-provider`, then the
+   canonical repository path is [github.com/pulumi/pulumi-terraform-provider/](https://github.com/pulumi/pulumi-terraform-provider/).
+
+2. [The registry](https://www.pulumi.com/registry) [expects](https://github.com/pulumi/registry/blob/39fc0592965e21a314a33c964db0a3e928c52aa4/tools/resourcedocsgen/cmd/pkgversion.go#L70-L91) each provider release to come from a repository with a semver tag:
+   `vX.Y.Z`. The bridge itself releases with those tags already, we would need to teach the registry to handle
+   nested tags.
+
+### Triggering a release
+
+To trigger a new release of `pulumi-terraform-provider`, push a new semver compatible tag to
+`pulumi-terraform-provider.
+
+### Final repository structure
+
+The complexity of maintaining a separate release repository to have a separate release cycle is
+sub-optimal. In the future, we should unify the release and code locations. We could either move the code to
+`pulumi-terraform-provider` or move the release process into `pulumi-terraform-bridge`.
+
+Moving the release process into [github.com/pulumi/pulumi-terraform-bridge](https://github.com/pulumi/pulumi-terraform-bridge/blob/master/dynamic) would require:
+
+- [Provide a centralized lookup for PluginDownloadURL #4851 ](https://github.com/pulumi/registry/issues/4851) (with CLI adoption)
+- [Support nested release labels #4852](https://github.com/pulumi/registry/issues/4852)