refactor: standardize on single @SInCE: version format

blink-so[bot] · matifali · blink-so[bot] · commit 898c99dae9b6 · 2025-06-27T18:32:23.000Z
Simplified the version metadata system to use a single @SInCE: format for both resources and attributes, eliminating confusion from having two different formats. Changes: - Updated all @minCoderVersion: markers to @SInCE: - Updated docsgen to only recognize @SInCE: format - Simplified version_meta.go - Updated documentation to reflect single format This makes the system more consistent and easier to use. 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,12 +3,12 @@
 page_title: "coder_ai_task Resource - terraform-provider-coder"
 subcategory: ""
 description: |-
-  Use this resource to define Coder tasks. @minCoderVersion:v2.24.0
+  Use this resource to define Coder tasks. @since:v2.24.0
 ---
 
 # coder_ai_task (Resource)
 
-Use this resource to define Coder tasks. @minCoderVersion:v2.24.0
+Use this resource to define Coder tasks. @since: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/devcontainer.md b/docs/resources/devcontainer.md
@@ -3,12 +3,12 @@
 page_title: "coder_devcontainer Resource - terraform-provider-coder"
 subcategory: ""
 description: |-
-  Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0
+  Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0
 ---
 
 # coder_devcontainer (Resource)
 
-Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0
+Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0
 
 ~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later.
 
diff --git a/provider/VERSION_METADATA.md b/provider/VERSION_METADATA.md
@@ -4,23 +4,23 @@ This document explains how to add version requirements to resources and attribut
 
 ## 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.
+Version information is embedded directly in resource and attribute descriptions using the `@since:` marker. 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:
+Add a `@since:` marker to the resource's `Description` field:
 
 ```go
-Description: "Your resource description. @minCoderVersion:v2.21.0",
+Description: "Your resource description. @since: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:
+Add a `@since:` marker to the attribute's `Description` field:
 
 ```go
 "my_attribute": {
@@ -32,17 +32,15 @@ Add a version marker to the attribute's `Description` field:
 
 This will result in the documentation showing: `- my_attribute (String) Attribute description. *(since v2.16.0)*`
 
-## Version Marker Formats
+## Version Marker Format
 
-You can use either format:
-- `@minCoderVersion:vX.Y.Z` - For resources
-- `@since:vX.Y.Z` - For attributes
+Use the format: `@since:vX.Y.Z`
 
-Both formats are recognized and processed the same way.
+This single format is used for both resources and attributes to maintain consistency.
 
 ## How It Works
 
-1. **During Development**: Add version markers to descriptions
+1. **During Development**: Add `@since:` markers to descriptions
 2. **During Doc Generation**: 
    - `terraform-plugin-docs` generates initial documentation
    - Our custom `docsgen` script:
@@ -58,7 +56,7 @@ Both formats are recognized and processed the same way.
 ```go
 func myNewResource() *schema.Resource {
     return &schema.Resource{
-        Description: "Manages a new Coder feature. @minCoderVersion:v2.25.0",
+        Description: "Manages a new Coder feature. @since:v2.25.0",
         // ... rest of resource definition
     }
 }
@@ -90,15 +88,19 @@ Results in documentation with:
 
 ## Default Versions
 
-- Resources without version markers default to `v2.18.0` (the base requirement)
-- Attributes without version markers don't show version information
+- Resources without `@since:` markers default to `v2.18.0` (the base requirement)
+- Attributes without `@since:` 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
+1. **Always add @since: 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
+5. **Use the version constants** from `version_meta.go` when available:
+   ```go
+   Description: "My feature. @since:" + provider.V2_21_0,
+   ```
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. @minCoderVersion:v2.24.0",
+                Description: "Use this resource to define Coder tasks. @since: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/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. @minCoderVersion:v2.21.0",
+                Description: "Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0",
 		CreateContext: func(_ context.Context, rd *schema.ResourceData, _ interface{}) diag.Diagnostics {
 			rd.SetId(uuid.NewString())
 
diff --git a/provider/version_meta.go b/provider/version_meta.go
@@ -1,14 +1,8 @@
 package provider
 
-// VersionMeta provides utilities for managing version metadata in resources.
+// VersionMeta provides utilities and constants 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
-}
+// using the @since: marker in their descriptions.
 
 // Common version constants for frequently used versions
 const (
diff --git a/scripts/docsgen/main.go b/scripts/docsgen/main.go
@@ -23,10 +23,10 @@ const docsDir = "docs" // FIXME expose as flag?
 
 var (
 	reDeprecatedProperty = regexp.MustCompile("`([^`]+)` \\(([^,\\)]+), Deprecated\\) ([^\n]+)")
-	// Pattern to extract version info from descriptions: @minCoderVersion:v2.16.0 or @since:v2.16.0
-	reVersionPattern = regexp.MustCompile(`@(?:minCoderVersion|since):(v\d+\.\d+\.\d+)`)
+	// Pattern to extract version info from descriptions: @since:v2.16.0
+	reVersionPattern = regexp.MustCompile(`@since:(v\d+\.\d+\.\d+)`)
 	// Pattern to find existing version info in descriptions (to clean up)
-	reExistingVersionInfo = regexp.MustCompile(`\s*\(@(?:minCoderVersion|since):[^)]+\)|\s*\(minimum Coder version:[^)]+\)`)
+	reExistingVersionInfo = regexp.MustCompile(`\s*\(@since:[^)]+\)|\s*\(minimum Coder version:[^)]+\)`)
 )
 
 func main() {
