feat: implement automated version documentation system

blink-so[bot] · matifali · blink-so[bot] · commit 2b138afea23a · 2025-06-27T18:32:23.000Z
Implements a maintainable system for documenting minimum Coder version
requirements for each resource and data source.

Changes:
- Add resource_versions.go with version registry that developers must update
- Modify docsgen to automatically inject version information into docs
- Add version compatibility matrix to provider index page
- Add developer documentation for maintaining version requirements
- All resources now show their minimum required Coder version

This ensures users can easily identify version requirements and prevents
compatibility issues.

Co-authored-by: matifali &lt;10648092+matifali@users.noreply.github.com&gt;
diff --git a/docs/data-sources/external_auth.md b/docs/data-sources/external_auth.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.)
 
+~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/data-sources/parameter.md b/docs/data-sources/parameter.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this data source to configure editable options for workspaces.
 
+~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/data-sources/provisioner.md b/docs/data-sources/provisioner.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this data source to get information about the Coder provisioner.
 
+~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/data-sources/workspace.md b/docs/data-sources/workspace.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this data source to get information for the active workspace build.
 
+~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/data-sources/workspace_owner.md b/docs/data-sources/workspace_owner.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this data source to fetch information about the workspace owner.
 
+~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/data-sources/workspace_preset.md b/docs/data-sources/workspace_preset.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace.
 
+~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/data-sources/workspace_tags.md b/docs/data-sources/workspace_tags.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this data source to configure workspace tags to select provisioners.
 
+~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/index.md b/docs/index.md
@@ -14,6 +14,20 @@ Terraform provider for managing Coder [templates](https://coder.com/docs/admin/t
 
 !> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/coder/coder/latest/docs/guides/version-2-upgrade) to update your code.
 
+## Version Compatibility
+
+The following table shows the minimum Coder version required for each terraform-provider-coder release:
+
+| Provider Version | Minimum Coder Version | Key Features |
+|------------------|-----------------------|--------------|
+| v2.8.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Default preset support |
+| v2.7.0+ | [v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) | AI task resource |
+| v2.6.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Scheduling configuration for prebuilds |
+| v2.5.0+ | [v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) | Devcontainer support |
+| v2.0.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Base requirement for v2 provider |
+
+~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version.
+
 ## Example
 
 ```terraform
diff --git a/docs/resources/agent.md b/docs/resources/agent.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this resource to associate an agent.
 
+~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/resources/agent_instance.md b/docs/resources/agent_instance.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for `"google_compute_instance"`, `"aws_instance"`, `"azurerm_linux_virtual_machine"`, and `"azurerm_windows_virtual_machine"` resources.
 
+~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/resources/app.md b/docs/resources/app.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this resource to define shortcuts to access applications in a workspace.
 
+~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/resources/devcontainer.md b/docs/resources/devcontainer.md
@@ -11,6 +11,8 @@ description: |-
 
 Define a Dev Container the agent should know of and attempt to autostart.
 
+~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later.
+
 -> This resource is only available in Coder v2.21 and later.
 
 
diff --git a/docs/resources/env.md b/docs/resources/env.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the `coder_agent` resource.
 
+~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/docs/resources/metadata.md b/docs/resources/metadata.md
@@ -11,6 +11,8 @@ description: |-
 
 Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. 
 
+~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 Alternatively, to attach metadata to the agent, use a `metadata` block within a `coder_agent` resource.
 
 ## Example Usage
diff --git a/docs/resources/script.md b/docs/resources/script.md
@@ -10,6 +10,8 @@ description: |-
 
 Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel.
 
+~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
+
 ## Example Usage
 
 ```terraform
diff --git a/provider/RESOURCE_VERSIONS.md b/provider/RESOURCE_VERSIONS.md
@@ -0,0 +1,50 @@
+# Resource Version Requirements
+
+This document explains how to maintain version requirements for terraform-provider-coder resources.
+
+## Overview
+
+The `resource_versions.go` file contains a registry of minimum Coder version requirements for each resource and data source. This information is automatically injected into the documentation during the build process.
+
+## Adding a New Resource
+
+When adding a new resource or data source, you MUST:
+
+1. Add an entry to the `ResourceVersions` map in `resource_versions.go`
+2. Set the minimum Coder version that supports this resource
+3. Run `make gen` to regenerate the documentation
+
+### Example
+
+```go
+var ResourceVersions = map[string]string{
+    // ... existing entries ...
+    "coder_new_resource": "v2.25.0", // Add your new resource here
+}
+```
+
+## Version Guidelines
+
+- **Default minimum**: v2.18.0 (the base requirement for terraform-provider-coder v2.0+)
+- **New features**: Use the Coder version where the feature was first introduced
+- **Attribute-level requirements**: Use the `AttributeVersions` map for attributes added after the resource itself
+
+## How It Works
+
+1. `terraform-plugin-docs` generates the initial documentation
+2. Our custom `docsgen` script reads the version registry
+3. Version notes are automatically added to each resource's documentation
+4. The version compatibility matrix in `index.md` is maintained manually in the template
+
+## Testing
+
+After adding or updating version information:
+
+1. Run `make gen`
+2. Check that the generated docs include the version note
+3. Verify the note appears after the resource description
+
+## Common Issues
+
+- **Missing version error**: If you see "no version information found", add the resource to `ResourceVersions`
+- **Duplicate notes**: If a resource already has version info in its Description, remove it and rely on the registry
diff --git a/provider/resource_versions.go b/provider/resource_versions.go
@@ -0,0 +1,33 @@
+package provider
+
+// ResourceVersions maps each resource and data source to its minimum required Coder version.
+// IMPORTANT: When adding a new resource or data source, you MUST add an entry here!
+// This ensures proper documentation of version requirements for users.
+var ResourceVersions = map[string]string{
+	// Resources
+	"coder_agent":          "v2.18.0", // Base requirement for terraform-provider-coder v2.0+
+	"coder_agent_instance": "v2.18.0",
+	"coder_ai_task":        "v2.24.0", // AI features introduced in v2.24.0
+	"coder_app":            "v2.18.0",
+	"coder_devcontainer":   "v2.21.0", // Devcontainer support added in v2.21.0
+	"coder_env":            "v2.18.0",
+	"coder_metadata":       "v2.18.0",
+	"coder_script":         "v2.18.0",
+
+	// Data Sources
+	"coder_external_auth":    "v2.18.0",
+	"coder_parameter":        "v2.18.0",
+	"coder_provisioner":      "v2.18.0",
+	"coder_workspace":        "v2.18.0",
+	"coder_workspace_owner":  "v2.18.0",
+	"coder_workspace_preset": "v2.18.0",
+	"coder_workspace_tags":   "v2.18.0",
+}
+
+// AttributeVersions maps specific resource attributes to their minimum required Coder version.
+// Use this for attributes that were added after the resource itself.
+var AttributeVersions = map[string]map[string]string{
+	"coder_app": {
+		"hidden": "v2.16.0", // Hidden attribute added in v2.16.0
+	},
+}
diff --git a/scripts/docsgen/main.go b/scripts/docsgen/main.go
@@ -14,7 +14,9 @@ import (
 	"golang.org/x/xerrors"
 )
 
-// This script patches Markdown docs generated by `terraform-plugin-docs` to expose the original deprecation message.
+// This script patches Markdown docs generated by `terraform-plugin-docs` to:
+// 1. Expose the original deprecation message
+// 2. Add minimum Coder version requirements
 
 const docsDir = "docs" // FIXME expose as flag?
 
@@ -26,6 +28,12 @@ func main() {
 	if err != nil {
 		log.Fatal(err)
 	}
+	
+	// Add version information to all resources and data sources
+	err = addVersionInformation(p)
+	if err != nil {
+		log.Fatal(err)
+	}
 }
 
 func exposeDeprecationMessage(p *schema.Provider) error {
@@ -87,3 +95,94 @@ func writeDeprecationMessage(doc []byte, schemas map[string]*schema.Schema) []by
 		return bytes.Replace(m, []byte("Deprecated"), []byte(fmt.Sprintf("**Deprecated**: %s", sch.Deprecated)), 1)
 	})
 }
+
+func addVersionInformation(p *schema.Provider) error {
+	// Add version info to data sources
+	for dataSourceName := range p.DataSourcesMap {
+		docFile := filepath.Join(docsDir, "data-sources", strings.Replace(dataSourceName, "coder_", "", 1)+".md")
+		if err := addVersionToDoc(docFile, dataSourceName); err != nil {
+			return xerrors.Errorf("unable to add version to data-source doc file (data-source: %s): %w", dataSourceName, err)
+		}
+	}
+
+	// Add version info to resources
+	for resourceName := range p.ResourcesMap {
+		docFile := filepath.Join(docsDir, "resources", strings.Replace(resourceName, "coder_", "", 1)+".md")
+		if err := addVersionToDoc(docFile, resourceName); err != nil {
+			return xerrors.Errorf("unable to add version to resource doc file (resource: %s): %w", resourceName, err)
+		}
+	}
+
+	return nil
+}
+
+func addVersionToDoc(docPath string, resourceName string) error {
+	version, ok := provider.ResourceVersions[resourceName]
+	if !ok {
+		return xerrors.Errorf("no version information found for %s. Please add it to provider.ResourceVersions", resourceName)
+	}
+
+	doc, err := os.ReadFile(docPath)
+	if err != nil {
+		return xerrors.Errorf("can't read the doc file: %w", err)
+	}
+
+	docStr := string(doc)
+	
+	// Check if version note already exists
+	if strings.Contains(docStr, "~> **Note:** This") && strings.Contains(docStr, "requires") && strings.Contains(docStr, "Coder") {
+		// Version note already exists, skip
+		return nil
+	}
+	
+	// Add version note after the description
+	versionNote := fmt.Sprintf("\n\n~> **Note:** This %s requires [Coder %s](https://github.com/coder/coder/releases/tag/%s) or later.",
+		getResourceType(resourceName), version, version)
+	
+	// Find the end of frontmatter
+	frontmatterEnd := -1
+	lines := strings.Split(docStr, "\n")
+	
+	if len(lines) > 0 && lines[0] == "---" {
+		for i := 1; i < len(lines); i++ {
+			if lines[i] == "---" {
+				frontmatterEnd = i
+				break
+			}
+		}
+	}
+	
+	// Find where to insert the version note
+	inserted := false
+	for i := frontmatterEnd + 1; i < len(lines); i++ {
+		// Skip empty lines and headings
+		if lines[i] == "" || strings.HasPrefix(lines[i], "#") {
+			continue
+		}
+		
+		// Insert after the first paragraph (non-empty, non-heading line)
+		lines[i] = lines[i] + versionNote
+		inserted = true
+		break
+	}
+	
+	if !inserted {
+		// If we couldn't find a good place, add it at the end
+		lines = append(lines, versionNote)
+	}
+	
+	docStr = strings.Join(lines, "\n")
+
+	err = os.WriteFile(docPath, []byte(docStr), 0644)
+	if err != nil {
+		return xerrors.Errorf("can't write modified doc file: %w", err)
+	}
+	return nil
+}
+
+func getResourceType(name string) string {
+	if strings.Contains(name, "data_source") || strings.Contains(name, "workspace") || strings.Contains(name, "provisioner") || strings.Contains(name, "parameter") || strings.Contains(name, "external_auth") {
+		return "data source"
+	}
+	return "resource"
+}
diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl
@@ -14,6 +14,20 @@ Terraform provider for managing Coder [templates](https://coder.com/docs/admin/t
 
 !> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/coder/coder/latest/docs/guides/version-2-upgrade) to update your code.
 
+## Version Compatibility
+
+The following table shows the minimum Coder version required for each terraform-provider-coder release:
+
+| Provider Version | Minimum Coder Version | Key Features |
+|------------------|-----------------------|--------------|
+| v2.8.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Default preset support |
+| v2.7.0+ | [v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) | AI task resource |
+| v2.6.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Scheduling configuration for prebuilds |
+| v2.5.0+ | [v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) | Devcontainer support |
+| v2.0.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Base requirement for v2 provider |
+
+~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version.
+
 ## Example
 
 {{tffile "examples/provider/provider.tf"}}
