From a92084db9ed3fa5abcf5c10e635e92d48475aa0c Mon Sep 17 00:00:00 2001
From: Ethan <39577870+ethanndickson@users.noreply.github.com>
Date: Thu, 5 Dec 2024 12:29:27 +1100
Subject: [PATCH] docs: update org resource (#151)

Output can be previewed by pasting the markdown into
https://registry.terraform.io/tools/doc-preview
---
 README.md                                     |  2 +-
 docs/resources/organization.md                | 26 ++++++++++++++-----
 .../resources/coderd_organization/import.sh   | 13 ++++++++--
 internal/provider/organization_resource.go    |  7 ++++-
 4 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 8eeafa0..e79f8eb 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ The provider currently supports resources and data sources for:
 - Templates + Template Versions
 - Groups
 - Workspace Proxies
-- Organizations (Data Source only)
+- Organizations
 
 ## Requirements
 
diff --git a/docs/resources/organization.md b/docs/resources/organization.md
index 9556be4..6dbc5d1 100644
--- a/docs/resources/organization.md
+++ b/docs/resources/organization.md
@@ -3,12 +3,17 @@
 page_title: "coderd_organization Resource - terraform-provider-coderd"
 subcategory: ""
 description: |-
-  An organization on the Coder deployment
+  An organization on the Coder deployment.
+  ~> Warning
+  This resource is only compatible with Coder version 2.16.0 https://github.com/coder/coder/releases/tag/v2.16.0 and later.
 ---
 
 # coderd_organization (Resource)
 
-An organization on the Coder deployment
+An organization on the Coder deployment.
+
+~> **Warning**
+This resource is only compatible with Coder version [2.16.0](https://github.com/coder/coder/releases/tag/v2.16.0) and later.
 
 
 
@@ -23,9 +28,9 @@ An organization on the Coder deployment
 
 - `description` (String)
 - `display_name` (String) Display name of the organization. Defaults to name.
-- `group_sync` (Block, Optional) (see [below for nested schema](#nestedblock--group_sync))
+- `group_sync` (Block, Optional) Group sync settings to sync groups from an IdP. (see [below for nested schema](#nestedblock--group_sync))
 - `icon` (String)
-- `role_sync` (Block, Optional) (see [below for nested schema](#nestedblock--role_sync))
+- `role_sync` (Block, Optional) Role sync settings to sync organization roles from an IdP. (see [below for nested schema](#nestedblock--role_sync))
 
 ### Read-Only
 
@@ -55,6 +60,15 @@ Optional:
 Import is supported using the following syntax:
 
 ```shell
-# Organizations can be imported by their name
-terraform import coderd_organization.our_org our_org
+# The ID supplied can be either a organization UUID retrieved via the API
+# or the name of the organization.
+$ terraform import coderd_organization.our_org our-org
+```
+Alternatively, in Terraform v1.5.0 and later, an [`import` block](https://developer.hashicorp.com/terraform/language/import) can be used:
+
+```terraform
+import {
+  to = coderd_organization.our_org
+  id = "our-org"
+}
 ```
diff --git a/examples/resources/coderd_organization/import.sh b/examples/resources/coderd_organization/import.sh
index 882dce6..45bb87a 100644
--- a/examples/resources/coderd_organization/import.sh
+++ b/examples/resources/coderd_organization/import.sh
@@ -1,2 +1,11 @@
-# Organizations can be imported by their name
-terraform import coderd_organization.our_org our_org
+# The ID supplied can be either a organization UUID retrieved via the API
+# or the name of the organization.
+$ terraform import coderd_organization.our_org our-org
+```
+Alternatively, in Terraform v1.5.0 and later, an [`import` block](https://developer.hashicorp.com/terraform/language/import) can be used:
+
+```terraform
+import {
+  to = coderd_organization.our_org
+  id = "our-org"
+}
diff --git a/internal/provider/organization_resource.go b/internal/provider/organization_resource.go
index 397f92e..2c39f0c 100644
--- a/internal/provider/organization_resource.go
+++ b/internal/provider/organization_resource.go
@@ -94,8 +94,11 @@ func (r *OrganizationResource) Metadata(ctx context.Context, req resource.Metada
 
 func (r *OrganizationResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
-		MarkdownDescription: "An organization on the Coder deployment",
+		MarkdownDescription: `An organization on the Coder deployment.
 
+~> **Warning**
+This resource is only compatible with Coder version [2.16.0](https://github.com/coder/coder/releases/tag/v2.16.0) and later.
+`,
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				CustomType:          UUIDType,
@@ -135,6 +138,7 @@ func (r *OrganizationResource) Schema(ctx context.Context, req resource.SchemaRe
 
 		Blocks: map[string]schema.Block{
 			"group_sync": schema.SingleNestedBlock{
+				MarkdownDescription: `Group sync settings to sync groups from an IdP.`,
 				Attributes: map[string]schema.Attribute{
 					"field": schema.StringAttribute{
 						Optional: true,
@@ -167,6 +171,7 @@ func (r *OrganizationResource) Schema(ctx context.Context, req resource.SchemaRe
 				},
 			},
 			"role_sync": schema.SingleNestedBlock{
+				MarkdownDescription: `Role sync settings to sync organization roles from an IdP.`,
 				Attributes: map[string]schema.Attribute{
 					"field": schema.StringAttribute{
 						Optional: true,