SUP-1432 v1.0 documentation updates (#408)

* Consolidate readme and changelog

* Restructure changelog

* Improve upgrade guide

* Remove banner from docs index

CHANGELOG.md

@@ -1,10 +1,14 @@
 # Changelog
 
-## Unreleased 
-All notable changes to this project will be documented in this file.
+## [v1.0.0](https://github.com/buildkite/terraform-provider-buildkite/compare/v0.27.0...v1.0.0) 🎉
 
-## v1.0.0-beta
+We are thrilled to release v1.0 of the Buildkite Terraform provider. This is the culmination of years of development and
+refactors to improve developer experience.
 
+### Upgrading to v1.0
+Please refer to the [Upgrade Guide](https://registry.terraform.io/providers/buildkite/buildkite/latest/docs/guides/upgrade-v1)
+
+### Changes
 - SUP-1394 Add validation to provider_settings [[PR #387](https://github.com/buildkite/terraform-provider-buildkite/pull/387)] @jradtilbrook
 - SUP-1382: Remove the deprecated team block from pipelines [[PR #391](https://github.com/buildkite/terraform-provider-buildkite/pull/391)] @lizrabuya
 - retryContextError util resource switch [[PR #394](https://github.com/buildkite/terraform-provider-buildkite/pull/394)] @james2791
@@ -17,8 +21,6 @@ All notable changes to this project will be documented in this file.
 - SUP-1444 Add cluster_default_queue resource [[PR #404](https://github.com/buildkite/terraform-provider-buildkite/pull/404)] @jradtilbrook
 - SUP-1446 Add enforce_2fa to organization resource [[PR #406](https://github.com/buildkite/terraform-provider-buildkite/pull/406)] @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.
-
 ## [v0.27.0](https://github.com/buildkite/terraform-provider-buildkite/compare/v0.26.0...v0.27.0)
 
 - SUP-805: SUP-805: Team resource retries [[PR #360](https://github.com/buildkite/terraform-provider-buildkite/pull/360)] @james2791

README.md

@@ -2,44 +2,19 @@
 
 [![Build status](https://badge.buildkite.com/7224047dadf711cab2facd75939ea39848850d7c5c5a765acd.svg?branch=main)](https://buildkite.com/buildkite/terraform-provider-buildkite-main)
 
-This is the official Terraform provider for [Buildkite](https://buildkite.com). The provider is listed in the [Terraform Registry](https://registry.terraform.io/) and supports terraform >= 0.13.
+This is the official Terraform provider for [Buildkite](https://buildkite.com). The provider is listed in the [Terraform Registry](https://registry.terraform.io/) and supports Terraform >= 1.0.
 
 The provider allows you to manage resources in your Buildkite organization.
 
 Two configuration values are required:
 
--   An API token, generated at https://buildkite.com/user/api-access-tokens. The
-    token must have the `write_pipelines`, `read_pipelines` and `write_suites` REST API scopes and be enabled for GraphQL API access.
--   A Buildkite organization slug, available by signing into buildkite.com and
-    examining the URL: https://buildkite.com/<org-slug>.
+-   An API token, generated at https://buildkite.com/user/api-access-tokens. The token must have the `write_pipelines`, `read_pipelines` and `write_suites` REST API scopes and be enabled for GraphQL API access.
+-   A Buildkite organization slug, available by signing into buildkite.com and examining the URL: https://buildkite.com/<org-slug>.
 
 ## Documentation
 
-The reference documentation on [the terraform registry](https://registry.terraform.io/providers/buildkite/buildkite/latest/docs)
-is the recommended location for guidance on using this provider.
+The reference documentation on [the terraform registry](https://registry.terraform.io/providers/buildkite/buildkite/latest/docs) is the recommended location for guidance on using this provider.
 
-## Installation
-
-**NOTE**: This provider is built with the assumption that teams are enabled for your Buildkite organization. Most resources should work without, but we can't guarantee compatibility. Check out our [documentation regarding teams](https://buildkite.com/docs/pipelines/permissions#permissions-with-teams) for more information.
-
-To use the provider, add the following terraform:
-
-```hcl
-terraform {
-  required_providers {
-    buildkite = {
-      source = "buildkite/buildkite"
-      version = "0.27.0"
-    }
-  }
-}
-
-provider "buildkite" {
-  # Configuration options
-  api_token = "token" # can also be set from env: BUILDKITE_API_TOKEN
-  organization = "slug" # can also be set from env: BUILDKITE_ORGANIZATION_SLUG
-}
-```
 
 ## Thanks :heart:
 
@@ -70,15 +45,8 @@ Buildkite has two APIs: REST and GraphQL. New resources should use the GraphQL A
 The repo contains a tf-proj/ directory that can be used to quickly test a compiled version of the provider from the current branch.
 
 1. Update tf-proj/main.tf to use the resource or property you're developing
-2. Compile the provider and copy it into the filesystem cache in tf-proj
-
-    ```bash
-      go build -o terraform-provider-buildkite . && \
-        mkdir -p tf-proj/terraform.d/plugins/registry.terraform.io/buildkite/buildkite/0.5.0/$(arch)/ && \
-        mv terraform-provider-buildkite tf-proj/terraform.d/plugins/registry.terraform.io/buildkite/buildkite/0.5.0/$(arch)/
-    ```
-
-3. Ensure the version number in the above command and in tf-proj/main.tf match
+2. Compile the provider with `make build`
+3. Add a `.terraformrc` configuration file to override the provider binary. See below: [Overriding the provider for local development](#overriding-the-provider-for-local-development)
 4. Run `terraform plan` in the tf-proj directory
 
     ```bash

buildkite/provider.go

@@ -146,8 +146,6 @@ 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: 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.27.0/docs
-
 			This provider can be used to manage resources on [buildkite.com](https://buildkite.com).
 		`),
 		Attributes: map[string]schema.Attribute{

buildkite/resource_pipeline.go

@@ -337,7 +337,7 @@ func (*pipelineResource) Schema(ctx context.Context, req resource.SchemaRequest,
 		MarkdownDescription: heredoc.Doc(`
 			This resource allows you to create and manage pipelines for repositories.
 
-			More information on pipelines can be found in the documentation](https://buildkite.com/docs/pipelines).
+			More information on pipelines can be found in the [documentation](https://buildkite.com/docs/pipelines).
 		`),
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{

docs/guides/upgrade-v1.md

@@ -5,19 +5,20 @@ page_title: Upgrading to v1.0
 # Upgrading to v1.0
 
 The Buildkite Terraform provider 1.0 is considered stable and ready for production use. If you have been using the
-provider prior to the 1.0 release, this guides you through upgrading.
+provider prior to the 1.0 release, this guides you through upgrading.  
+If you are starting a new terraform project with this provider, you can start at https://registry.terraform.io/providers/buildkite/buildkite/latest/docs.
 
 ## New Features
 
 ### Protocol version 6
 The provider has been upgraded to protocol v6. It is therefor only compatible with terraform CLI version 1.0 and later.
 
 ### Cluster resources
-You are now able to manage cluster resources with the provider. This includes `cluster`, `cluster_queue`, and
-`cluster_agent_token`.
+You are now able to manage cluster resources with the provider. This includes [`buildkite_cluster`](../resources/cluster)., [`buildkite_cluster_queue`](../resources/cluster_queue), and
+[`buildkite_cluster_agent_token`](../resources/cluster_agent_token).
 
 ### Test Analytics resources
-You can now create test suites and assign teams access to them with `test_suite`, and `test_suite_team`.
+You can now create test suites and assign teams access to them with [`buildkite_test_suite`](../resources/test_suite), and [`buildkite_test_suite_team`](../resources/test_suite_team).
 
 ### Configurable API retry timeouts
 API retries and timeouts have been implemented in the majority of resources. This adds reliability to the provider
@@ -76,24 +77,29 @@ resource "buildkite_pipeline" "pipeline" {
 }
 ```
 
-~> The upgrade for a pipeline's `provider_settings` as part of 1.0 from a block to nested attribute is designed to be a forward moving event. However, if you require moving back to using a Buildkite Terraform provider version earlier than 1.0 after upgrading your pipeline resources with nested attributed `provider_settings`, various options exist. If you have access to state files, you can roll back to a backup managing pipelines using the older block `provider_settings` (with `"schema_version": 0`), converting each pipeline resource's `provider_settings` configuration back to a block and planning against the older provider version. Alternatively, you can remove the pipeline from state and re-import it once the provider downgrade has occurred.
-
 ### Consistent IDs across resources
 All resources now use their GraphQL IDs as the primary ID in the schema.
 
 ## Removed Features
 
-- `team` attribute on pipeline resource has been removed.
+- `team` attribute on pipeline resource has been removed. It is replaced by the separate resource [`buildkite_pipeline_team`](../resources/pipeline_team).
 
 ## 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.
 
+### Backup the state file
+
+State file backups are created automatically by terraform. You should inspect your state storage location and ensure
+there is a valid backup available in the event of corruption from upgrading the provider.
+
+Refer to https://developer.hashicorp.com/terraform/cli/state/recover for more information.
+
 ### Pin provider version
 
-You should pin your provider installation to the 1.x releases.
+You should pin your provider installation to the 1.x releases so you can upgrade as new versions are released.
 
 ```tf
 terraform {
@@ -118,7 +124,7 @@ 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:
-[`pipeline_team`](../resources/pipeline_team).
+[`buildkite_pipeline_team`](../resources/pipeline_team).
 
 You'll need to upgrade your provider to version `0.27.0` and switch over to the new resource prior to upgrading to v1.0.
 
@@ -205,3 +211,17 @@ Terraform will perform the following actions:
 
 Plan: 1 to add, 1 to change, 0 to destroy.
 ```
+
+### Migrate `pipeline.provider_settings` block to a nested attribute
+
+This is as simple as adding an equal sign (`=`) to the `provider_settings` attribute and running `terraform apply`.
+
+The provider will transparently update the state file to the new schema version. This operation is not automatically
+reversible. If you run into issues from upgrading, please raise an issue on GitHub.
+
+See [Pipeline resource `provider_settings` type change](./upgrade-v1#pipeline-resource-provider_settings-type-change) for an example.
+
+#### Rolling back
+
+If you experience issues with the automatic upgrade you can revert your changes and re-instate the backup terraform
+state file. Follow the instructions from Terraform on disaster recovery: https://developer.hashicorp.com/terraform/cli/state/recover.

docs/index.md

@@ -3,14 +3,11 @@
 page_title: "buildkite Provider"
 subcategory: ""
 description: |-
-  ~> 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.27.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.27.0/docs
-
 This provider can be used to manage resources on [buildkite.com](https://buildkite.com).
 
 ## Example Usage

docs/resources/pipeline.md

@@ -4,14 +4,14 @@ page_title: "buildkite_pipeline Resource - terraform-provider-buildkite"
 subcategory: ""
 description: |-
   This resource allows you to create and manage pipelines for repositories.
-  More information on pipelines can be found in the documentation](https://buildkite.com/docs/pipelines).
+  More information on pipelines can be found in the documentation https://buildkite.com/docs/pipelines.
 ---
 
 # buildkite_pipeline (Resource)
 
 This resource allows you to create and manage pipelines for repositories.
 
-More information on pipelines can be found in the documentation](https://buildkite.com/docs/pipelines).
+More information on pipelines can be found in the [documentation](https://buildkite.com/docs/pipelines).
 
 ## Example Usage
 

templates/guides/upgrade-v1.md

@@ -5,19 +5,20 @@ page_title: Upgrading to v1.0
 # Upgrading to v1.0
 
 The Buildkite Terraform provider 1.0 is considered stable and ready for production use. If you have been using the
-provider prior to the 1.0 release, this guides you through upgrading.
+provider prior to the 1.0 release, this guides you through upgrading.  
+If you are starting a new terraform project with this provider, you can start at https://registry.terraform.io/providers/buildkite/buildkite/latest/docs.
 
 ## New Features
 
 ### Protocol version 6
 The provider has been upgraded to protocol v6. It is therefor only compatible with terraform CLI version 1.0 and later.
 
 ### Cluster resources
-You are now able to manage cluster resources with the provider. This includes `cluster`, `cluster_queue`, and
-`cluster_agent_token`.
+You are now able to manage cluster resources with the provider. This includes [`buildkite_cluster`](../resources/cluster)., [`buildkite_cluster_queue`](../resources/cluster_queue), and
+[`buildkite_cluster_agent_token`](../resources/cluster_agent_token).
 
 ### Test Analytics resources
-You can now create test suites and assign teams access to them with `test_suite`, and `test_suite_team`.
+You can now create test suites and assign teams access to them with [`buildkite_test_suite`](../resources/test_suite), and [`buildkite_test_suite_team`](../resources/test_suite_team).
 
 ### Configurable API retry timeouts
 API retries and timeouts have been implemented in the majority of resources. This adds reliability to the provider
@@ -76,24 +77,29 @@ resource "buildkite_pipeline" "pipeline" {
 }
 ```
 
-~> The upgrade for a pipeline's `provider_settings` as part of 1.0 from a block to nested attribute is designed to be a forward moving event. However, if you require moving back to using a Buildkite Terraform provider version earlier than 1.0 after upgrading your pipeline resources with nested attributed `provider_settings`, various options exist. If you have access to state files, you can roll back to a backup managing pipelines using the older block `provider_settings` (with `"schema_version": 0`), converting each pipeline resource's `provider_settings` configuration back to a block and planning against the older provider version. Alternatively, you can remove the pipeline from state and re-import it once the provider downgrade has occurred.
-
 ### Consistent IDs across resources
 All resources now use their GraphQL IDs as the primary ID in the schema.
 
 ## Removed Features
 
-- `team` attribute on pipeline resource has been removed.
+- `team` attribute on pipeline resource has been removed. It is replaced by the separate resource [`buildkite_pipeline_team`](../resources/pipeline_team).
 
 ## 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.
 
+### Backup the state file
+
+State file backups are created automatically by terraform. You should inspect your state storage location and ensure
+there is a valid backup available in the event of corruption from upgrading the provider.
+
+Refer to https://developer.hashicorp.com/terraform/cli/state/recover for more information.
+
 ### Pin provider version
 
-You should pin your provider installation to the 1.x releases.
+You should pin your provider installation to the 1.x releases so you can upgrade as new versions are released.
 
 ```tf
 terraform {
@@ -118,7 +124,7 @@ 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:
-[`pipeline_team`](../resources/pipeline_team).
+[`buildkite_pipeline_team`](../resources/pipeline_team).
 
 You'll need to upgrade your provider to version `0.27.0` and switch over to the new resource prior to upgrading to v1.0.
 
@@ -205,3 +211,17 @@ Terraform will perform the following actions:
 
 Plan: 1 to add, 1 to change, 0 to destroy.
 ```
+
+### Migrate `pipeline.provider_settings` block to a nested attribute
+
+This is as simple as adding an equal sign (`=`) to the `provider_settings` attribute and running `terraform apply`.
+
+The provider will transparently update the state file to the new schema version. This operation is not automatically
+reversible. If you run into issues from upgrading, please raise an issue on GitHub.
+
+See [Pipeline resource `provider_settings` type change](./upgrade-v1#pipeline-resource-provider_settings-type-change) for an example.
+
+#### Rolling back
+
+If you experience issues with the automatic upgrade you can revert your changes and re-instate the backup terraform
+state file. Follow the instructions from Terraform on disaster recovery: https://developer.hashicorp.com/terraform/cli/state/recover.