SUP-1431 Upgrade path for pipeline teams (#401)

* Improve docs around upgrade path for pipeline teams

* Add note about team upgrade

* Update changelog

* Add doc note about pre-release

CHANGELOG.md

@@ -11,6 +11,7 @@ All notable changes to this project will be documented in this file.
 - Added `build_pull_request_ready_for_review` to pipeline resource docs/examples/tests [[PR #396](https://github.com/buildkite/terraform-provider-buildkite/pull/396)] @james2791
 - SUP-1370 Update to protocol v6 [[PR #400](https://github.com/buildkite/terraform-provider-buildkite/pull/400)] @jradtilbrook
 - SUP-1293 Generate docs from code [[PR #397](https://github.com/buildkite/terraform-provider-buildkite/pull/397)] @jradtilbrook
+- SUP-1431 Upgrade path for pipeline teams [[PR #401](https://github.com/buildkite/terraform-provider-buildkite/pull/401)] @jradtilbrook
 
 The `team` block from the `buildkite_pipeline` resource has been removed. Please use the resource `buildkite_pipeline_team` to create and manage team configuration in a pipeline.
 

buildkite/provider.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/hashicorp/terraform-plugin-framework-timeouts/resource/timeouts"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/provider"
@@ -143,9 +144,11 @@ func (tf *terraformProvider) Resources(context.Context) []func() resource.Resour
 
 func (*terraformProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: `
-		This provider can be used to manage resources on [buildkite.com](https://buildkite.com).
-		`,
+		MarkdownDescription: heredoc.Doc(`
+			~> You are viewing documentation for a pre-release version of the provider. Please see the latest stable docs at https://registry.terraform.io/providers/buildkite/buildkite/0.26.0/docs
+
+			This provider can be used to manage resources on [buildkite.com](https://buildkite.com).
+		`),
 		Attributes: map[string]schema.Attribute{
 			SchemaKeyOrganization: schema.StringAttribute{
 				Optional:            true,

docs/guides/upgrade-v1.md

@@ -85,6 +85,10 @@ All resources now use their GraphQL IDs as the primary ID in the schema.
 
 ## Upgrade Guide
 
+~> If you are coming from a 0.x release of the provider and using `buildkite_pipeline.team` attribute on your resources,
+you **must** upgrade to version 0.27.0 prior to upgrading to v1.0. See [Migrate pipeline.team usage to pipeline_team
+resource](./upgrade-v1#migrate-pipelineteam-usage-to-pipeline_team-resource) for more info.
+
 ### Pin provider version
 
 You should pin your provider installation to the 1.x releases.
@@ -100,6 +104,15 @@ terraform {
 }
 ```
 
+### Upgrade provider
+
+After pinning the provider version, you can upgrade it by running: `terraform init -upgrade`. This will pull in the
+latest release under the 1.x version.
+
+### Refresh state
+
+The next step is to refresh your state file: `terraform refresh`.
+
 ### Migrate `pipeline.team` usage to `pipeline_team` resource
 
 The `team` attribute on the `pipeline` resource was removed in v1.0 in favour of a separate resource:
@@ -150,3 +163,43 @@ resource "buildkite_pipeline_team" "deploy_pipeline" {
   access_level = "BUILD_AND_READ"
 }
 ```
+
+After applying that change to all `pipeline` resources with a `team` attribute, you can run an apply: `terraform apply`.
+
+This will show something like below. You can see in the plan that it will temporarily remove the team from the pipeline,
+then followup with adding it back through the separate resource. This will result in a very small time window where the
+team doesn't have access to the pipeline. It should be unnoticeable.
+
+```
+Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
+  + create
+  ~ update in-place
+
+Terraform will perform the following actions:
+
+  # buildkite_pipeline.pipeline will be updated in-place
+  ~ resource "buildkite_pipeline" "pipeline" {
+        id                         = "<obfuscated>"
+        name                       = "v0.27"
+        tags                       = []
+        # (10 unchanged attributes hidden)
+
+      - team {
+          - access_level     = "READ_ONLY" -> null
+          - pipeline_team_id = "<obfuscated>" -> null
+          - slug             = "team" -> null
+          - team_id          = "<obfuscated>" -> null
+        }
+    }
+
+  # buildkite_pipeline_team.p_team will be created
+  + resource "buildkite_pipeline_team" "p_team" {
+      + access_level = "READ_ONLY"
+      + id           = (known after apply)
+      + pipeline_id  = "<obfuscated>"
+      + team_id      = "<obfuscated>"
+      + uuid         = (known after apply)
+    }
+
+Plan: 1 to add, 1 to change, 0 to destroy.
+```

docs/index.md

@@ -3,11 +3,14 @@
 page_title: "buildkite Provider"
 subcategory: ""
 description: |-
-  This provider can be used to manage resources on [buildkite.com](https://buildkite.com).
+  ~> You are viewing documentation for a pre-release version of the provider. Please see the latest stable docs at https://registry.terraform.io/providers/buildkite/buildkite/0.26.0/docs
+  This provider can be used to manage resources on buildkite.com https://buildkite.com.
 ---
 
 # buildkite Provider
 
+~> You are viewing documentation for a pre-release version of the provider. Please see the latest stable docs at https://registry.terraform.io/providers/buildkite/buildkite/0.26.0/docs
+
 This provider can be used to manage resources on [buildkite.com](https://buildkite.com).
 
 ## Example Usage

templates/guides/upgrade-v1.md

@@ -85,6 +85,10 @@ All resources now use their GraphQL IDs as the primary ID in the schema.
 
 ## Upgrade Guide
 
+~> If you are coming from a 0.x release of the provider and using `buildkite_pipeline.team` attribute on your resources,
+you **must** upgrade to version 0.27.0 prior to upgrading to v1.0. See [Migrate pipeline.team usage to pipeline_team
+resource](./upgrade-v1#migrate-pipelineteam-usage-to-pipeline_team-resource) for more info.
+
 ### Pin provider version
 
 You should pin your provider installation to the 1.x releases.
@@ -100,6 +104,15 @@ terraform {
 }
 ```
 
+### Upgrade provider
+
+After pinning the provider version, you can upgrade it by running: `terraform init -upgrade`. This will pull in the
+latest release under the 1.x version.
+
+### Refresh state
+
+The next step is to refresh your state file: `terraform refresh`.
+
 ### Migrate `pipeline.team` usage to `pipeline_team` resource
 
 The `team` attribute on the `pipeline` resource was removed in v1.0 in favour of a separate resource:
@@ -150,3 +163,43 @@ resource "buildkite_pipeline_team" "deploy_pipeline" {
   access_level = "BUILD_AND_READ"
 }
 ```
+
+After applying that change to all `pipeline` resources with a `team` attribute, you can run an apply: `terraform apply`.
+
+This will show something like below. You can see in the plan that it will temporarily remove the team from the pipeline,
+then followup with adding it back through the separate resource. This will result in a very small time window where the
+team doesn't have access to the pipeline. It should be unnoticeable.
+
+```
+Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
+  + create
+  ~ update in-place
+
+Terraform will perform the following actions:
+
+  # buildkite_pipeline.pipeline will be updated in-place
+  ~ resource "buildkite_pipeline" "pipeline" {
+        id                         = "<obfuscated>"
+        name                       = "v0.27"
+        tags                       = []
+        # (10 unchanged attributes hidden)
+
+      - team {
+          - access_level     = "READ_ONLY" -> null
+          - pipeline_team_id = "<obfuscated>" -> null
+          - slug             = "team" -> null
+          - team_id          = "<obfuscated>" -> null
+        }
+    }
+
+  # buildkite_pipeline_team.p_team will be created
+  + resource "buildkite_pipeline_team" "p_team" {
+      + access_level = "READ_ONLY"
+      + id           = (known after apply)
+      + pipeline_id  = "<obfuscated>"
+      + team_id      = "<obfuscated>"
+      + uuid         = (known after apply)
+    }
+
+Plan: 1 to add, 1 to change, 0 to destroy.
+```