refactor: implement inline version metadata system

blink-so[bot] · matifali · blink-so[bot] · commit 309930bf0945 · 2025-06-27T15:39:51.000Z
Refactored the version documentation system to store version requirements directly in resource and attribute descriptions, eliminating the need for an external registry file. Changes: - Removed external resource_versions.go registry - Added version metadata markers in descriptions (@minCoderVersion, @SInCE) - Enhanced docsgen to extract and format version information - Added inline version markers for attributes with non-default versions - Created developer documentation for the new system This approach keeps version information close to the code, making it easier to maintain and harder to forget when adding new features. Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>
diff --git a/docs/resources/ai_task.md b/docs/resources/ai_task.md
@@ -3,13 +3,12 @@
 page_title: "coder_ai_task Resource - terraform-provider-coder"
 subcategory: ""
 description: |-
-  Use this resource to define Coder tasks.
-  ~> Note: This resource requires Coder v2.24.0 https://github.com/coder/coder/releases/tag/v2.24.0 or later.
+  Use this resource to define Coder tasks. @minCoderVersion:v2.24.0
 ---
 
 # coder_ai_task (Resource)
 
-Use this resource to define Coder tasks.
+Use this resource to define Coder tasks. @minCoderVersion:v2.24.0
 
 ~> **Note:** This resource requires [Coder v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later.
 
diff --git a/docs/resources/app.md b/docs/resources/app.md
@@ -67,7 +67,7 @@ resource "coder_app" "vim" {
 - `external` (Boolean) Specifies whether `url` is opened on the client machine instead of proxied through the workspace.
 - `group` (String) The name of a group that this app belongs to.
 - `healthcheck` (Block Set, Max: 1) HTTP health checking to determine the application readiness. (see [below for nested schema](#nestedblock--healthcheck))
-- `hidden` (Boolean) Determines if the app is visible in the UI (minimum Coder version: v2.16).
+- `hidden` (Boolean) Determines if the app is visible in the UI. *(since v2.16.0)*
 - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/<path>"`.
 - `open_in` (String) Determines where the app will be opened. Valid values are `"tab"` and `"slim-window" (default)`. `"tab"` opens in a new tab in the same browser window. `"slim-window"` opens a new browser window without navigation controls.
 - `order` (Number) The order determines the position of app in the UI presentation. The lowest order is shown first and apps with equal order are sorted by name (ascending order).
diff --git a/docs/resources/devcontainer.md b/docs/resources/devcontainer.md
@@ -3,18 +3,15 @@
 page_title: "coder_devcontainer Resource - terraform-provider-coder"
 subcategory: ""
 description: |-
-  Define a Dev Container the agent should know of and attempt to autostart.
-  -> This resource is only available in Coder v2.21 and later.
+  Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0
 ---
 
 # coder_devcontainer (Resource)
 
-Define a Dev Container the agent should know of and attempt to autostart.
+Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0
 
 ~> **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.
-
 
 
 <!-- schema generated by tfplugindocs -->
diff --git a/provider/RESOURCE_VERSIONS.md b/provider/RESOURCE_VERSIONS.md
diff --git a/provider/VERSION_METADATA.md b/provider/VERSION_METADATA.md
@@ -0,0 +1,104 @@
+# Version Metadata Documentation
+
+This document explains how to add version requirements to resources and attributes in the terraform-provider-coder.
+
+## Overview
+
+Version information is embedded directly in resource and attribute descriptions using special markers. The documentation generation process automatically extracts this information and formats it appropriately.
+
+## Adding Version Requirements
+
+### For Resources
+
+Add a version marker to the resource's `Description` field:
+
+```go
+Description: "Your resource description. @minCoderVersion:v2.21.0",
+```
+
+The marker will be automatically removed from the generated docs and replaced with a formatted note.
+
+### For Attributes
+
+Add a version marker to the attribute's `Description` field:
+
+```go
+"my_attribute": {
+    Type:        schema.TypeString,
+    Description: "Attribute description. @since:v2.16.0",
+    Optional:    true,
+},
+```
+
+This will result in the documentation showing: `- my_attribute (String) Attribute description. *(since v2.16.0)*`
+
+## Version Marker Formats
+
+You can use either format:
+- `@minCoderVersion:vX.Y.Z` - For resources
+- `@since:vX.Y.Z` - For attributes
+
+Both formats are recognized and processed the same way.
+
+## How It Works
+
+1. **During Development**: Add version markers to descriptions
+2. **During Doc Generation**: 
+   - `terraform-plugin-docs` generates initial documentation
+   - Our custom `docsgen` script:
+     - Extracts version information from descriptions
+     - Adds formatted version notes to resources
+     - Adds inline version markers to attributes
+     - Cleans up the version patterns from descriptions
+
+## Examples
+
+### Resource Example
+
+```go
+func myNewResource() *schema.Resource {
+    return &schema.Resource{
+        Description: "Manages a new Coder feature. @minCoderVersion:v2.25.0",
+        // ... rest of resource definition
+    }
+}
+```
+
+Results in documentation with:
+```markdown
+# coder_my_new (Resource)
+
+Manages a new Coder feature.
+
+~> **Note:** This resource requires [Coder v2.25.0](https://github.com/coder/coder/releases/tag/v2.25.0) or later.
+```
+
+### Attribute Example
+
+```go
+"advanced_option": {
+    Type:        schema.TypeBool,
+    Description: "Enable advanced features. @since:v2.22.0",
+    Optional:    true,
+},
+```
+
+Results in documentation with:
+```markdown
+- `advanced_option` (Boolean) Enable advanced features. *(since v2.22.0)*
+```
+
+## Default Versions
+
+- Resources without version markers default to `v2.18.0` (the base requirement)
+- Attributes without version markers don't show version information
+- Special resources have hardcoded defaults:
+  - `coder_devcontainer`: v2.21.0
+  - `coder_ai_task`: v2.24.0
+
+## Best Practices
+
+1. **Always add version markers** when creating new resources or attributes
+2. **Use semantic versioning** (vX.Y.Z format)
+3. **Test documentation generation** with `make gen` after adding markers
+4. **Keep descriptions concise** - the version marker is removed from the final docs
diff --git a/provider/ai_task.go b/provider/ai_task.go
@@ -25,7 +25,7 @@ func aiTask() *schema.Resource {
 	return &schema.Resource{
 		SchemaVersion: 1,
 
-		Description: "Use this resource to define Coder tasks.\n\n~> **Note:** This resource requires [Coder v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later.",
+                Description: "Use this resource to define Coder tasks. @minCoderVersion:v2.24.0",
 		CreateContext: func(c context.Context, resourceData *schema.ResourceData, i any) diag.Diagnostics {
 			resourceData.SetId(uuid.NewString())
 			return nil
diff --git a/provider/app.go b/provider/app.go
@@ -251,7 +251,7 @@ func appResource() *schema.Resource {
 			},
 			"hidden": {
 				Type:        schema.TypeBool,
-				Description: "Determines if the app is visible in the UI (minimum Coder version: v2.16).",
+				Description: "Determines if the app is visible in the UI. @since:v2.16.0",
 				Default:     false,
 				ForceNew:    true,
 				Optional:    true,
diff --git a/provider/devcontainer.go b/provider/devcontainer.go
@@ -13,7 +13,7 @@ func devcontainerResource() *schema.Resource {
 	return &schema.Resource{
 		SchemaVersion: 1,
 
-		Description: "Define a Dev Container the agent should know of and attempt to autostart.\n\n-> This resource is only available in Coder v2.21 and later.",
+                Description: "Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0",
 		CreateContext: func(_ context.Context, rd *schema.ResourceData, _ interface{}) diag.Diagnostics {
 			rd.SetId(uuid.NewString())
 
diff --git a/provider/resource_versions.go b/provider/resource_versions.go
diff --git a/provider/version_meta.go b/provider/version_meta.go
@@ -0,0 +1,26 @@
+package provider
+
+// VersionMeta provides utilities for managing version metadata in resources.
+// Resources and attributes can specify their minimum Coder version requirements
+// using these utilities.
+
+// MinCoderVersion is a helper function that returns a formatted version string
+// for use in resource descriptions. This ensures consistent formatting.
+func MinCoderVersion(version string) string {
+	return "@minCoderVersion:" + version
+}
+
+// Common version constants for frequently used versions
+const (
+	// V2_18_0 is the base requirement for terraform-provider-coder v2.0+
+	V2_18_0 = "v2.18.0"
+	
+	// V2_16_0 introduced the hidden attribute for apps
+	V2_16_0 = "v2.16.0"
+	
+	// V2_21_0 introduced devcontainer support
+	V2_21_0 = "v2.21.0"
+	
+	// V2_24_0 introduced AI task resources
+	V2_24_0 = "v2.24.0"
+)
diff --git a/scripts/docsgen/main.go b/scripts/docsgen/main.go
