8000 refactor: standardize on single @since: version format · coder/terraform-provider-coder@2eff7b3 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2eff7b3

Browse files
blink-so[bot]matifali
blink-so[bot]
and
matifali
committed
refactor: standardize on single @SInCE: version format
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>
1 parent 309930b commit 2eff7b3

File tree

7 files changed

+27
-31
lines changed

7 files changed

+27
-31
lines changed

‎docs/resources/ai_task.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
page_title: "coder_ai_task Resource - terraform-provider-coder"
44
subcategory: ""
55
description: |-
6-
Use this resource to define Coder tasks. @minCoderVersion:v2.24.0
6+
Use this resource to define Coder tasks. @since:v2.24.0
77
---
88

99
# coder_ai_task (Resource)
1010

11-
Use this resource to define Coder tasks. @minCoderVersion:v2.24.0
11+
Use this resource to define Coder tasks. @since:v2.24.0
1212

1313
~> **Note:** This resource requires [Coder v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later.
1414

‎docs/resources/devcontainer.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
page_title: "coder_devcontainer Resource - terraform-provider-coder"
44
subcategory: ""
55
description: |-
6-
Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0
6+
Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0
77
---
88

99
# coder_devcontainer (Resource)
1010

11-
Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0
11+
Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0
1212

1313
~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later.
1414

‎provider/VERSION_METADATA.md

Lines changed: 16 additions & 14 deletions
+
Add a `@since:` marker to the attribute's `Description` field:
Original file line numberDiff line numberDiff line change
@@ -4,23 +4,23 @@ This document explains how to add version requirements to resources and attribut
44

55
## Overview
66

7-
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.
7+
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.
88

99
## Adding Version Requirements
1010

1111
### For Resources
1212

13-
Add a version marker to the resource's `Description` field:
13+
Add a `@since:` marker to the resource's `Description` field:
1414

1515
```go
16-
Description: "Your resource description. @minCoderVersion:v2.21.0",
16+
Description: "Your resource description. @since:v2.21.0",
1717
```
1818

1919
The marker will be automatically removed from the generated docs and replaced with a formatted note.
2020

2121
### For Attributes
2222

23-
Add a version marker to the attribute's `Description` field:
23
2424

2525
```go
2626
"my_attribute": {
@@ -32,17 +32,15 @@ Add a version marker to the attribute's `Description` field:
3232

3333
This will result in the documentation showing: `- my_attribute (String) Attribute description. *(since v2.16.0)*`
3434

35-
## Version Marker Formats
35+
## Version Marker Format
3636

37-
You can use either format:
38-
- `@minCoderVersion:vX.Y.Z` - For resources
39-
- `@since:vX.Y.Z` - For attributes
37+
Use the format: `@since:vX.Y.Z`
4038

41-
Both formats are recognized and processed the same way.
39+
This single format is used for both resources and attributes to maintain consistency.
4240

4341
## How It Works
4442

45-
1. **During Development**: Add version markers to descriptions
43+
1. **During Development**: Add `@since:` markers to descriptions
4644
2. **During Doc Generation**:
4745
- `terraform-plugin-docs` generates initial documentation
4846
- Our custom `docsgen` script:
@@ -58,7 +56,7 @@ Both formats are recognized and processed the same way.
5856
```go
5957
func myNewResource() *schema.Resource {
6058
return &schema.Resource{
61-
Description: "Manages a new Coder feature. @minCoderVersion:v2.25.0",
59+
Description: "Manages a new Coder feature. @since:v2.25.0",
6260
// ... rest of resource definition
6361
}
6462
}
@@ -90,15 +88,19 @@ Results in documentation with:
9088

9189
## Default Versions
9290

93-
- Resources without version markers default to `v2.18.0` (the base requirement)
94-
- Attributes without version markers don't show version information
91+
- Resources without `@since:` markers default to `v2.18.0` (the base requirement)
92+
- Attributes without `@since:` markers don't show version information
9593
- Special resources have hardcoded defaults:
9694
- `coder_devcontainer`: v2.21.0
9795
- `coder_ai_task`: v2.24.0
9896

9997
## Best Practices
10098

101-
1. **Always add version markers** when creating new resources or attributes
99+
1. **Always add @since: markers** when creating new resources or attributes
102100
2. **Use semantic versioning** (vX.Y.Z format)
103101
3. **Test documentation generation** with `make gen` after adding markers
104102
4. **Keep descriptions concise** - the version marker is removed from the final docs
103+
5. **Use the version constants** from `version_meta.go` when available:
104+
```go
105+
Description: "My feature. @since:" + provider.V2_21_0,
106+
```

‎provider/ai_task.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ func aiTask() *schema.Resource {
2525
return &schema.Resource{
2626
SchemaVersion: 1,
2727

28-
Description: "Use this resource to define Coder tasks. @minCoderVersion:v2.24.0",
28+
Description: "Use this resource to define Coder tasks. @since:v2.24.0",
2929
CreateContext: func(c context.Context, resourceData *schema.ResourceData, i any) diag.Diagnostics {
3030
resourceData.SetId(uuid.NewString())
3131
return nil

‎provider/devcontainer.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ func devcontainerResource() *schema.Resource {
1313
return &schema.Resource{
1414
SchemaVersion: 1,
1515

16-
Description: "Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0",
16+
Description: "Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0",
1717
CreateContext: func(_ context.Context, rd *schema.ResourceData, _ interface{}) diag.Diagnostics {
1818
rd.SetId(uuid.NewString())
1919

‎provider/version_meta.go

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,8 @@
11
package provider
22

3-
// VersionMeta provides utilities for managing version metadata in resources.
3+
// VersionMeta provides utilities and constants for managing version metadata in resources.
44
// Resources and attributes can specify their minimum Coder version requirements
5-
// using these utilities.
6-
7-
// MinCoderVersion is a helper function that returns a formatted version string
8-
// for use in resource descriptions. This ensures consistent formatting.
9-
func MinCoderVersion(version string) string {
10-
return "@minCoderVersion:" + version
11-
}
5+
// using the @since: marker in their descriptions.
126

137
// Common version constants for frequently used versions
148
const (

‎scripts/docsgen/main.go

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ const docsDir = "docs" // FIXME expose as flag?
2323

2424
var (
2525
reDeprecatedProperty = regexp.MustCompile("`([^`]+)` \\(([^,\\)]+), Deprecated\\) ([^\n]+)")
26-
// Pattern to extract version info from descriptions: @minCoderVersion:v2.16.0 or @since:v2.16.0
27-
reVersionPattern = regexp.MustCompile(`@(?:minCoderVersion|since):(v\d+\.\d+\.\d+)`)
26+
// Pattern to extract version info from descriptions: @since:v2.16.0
27+
reVersionPattern = regexp.MustCompile(`@since:(v\d+\.\d+\.\d+)`)
2828
// Pattern to find existing version info in descriptions (to clean up)
29-
reExistingVersionInfo = regexp.MustCompile(`\s*\(@(?:minCoderVersion|since):[^)]+\)|\s*\(minimum Coder version:[^)]+\)`)
29+
reExistingVersionInfo = regexp.MustCompile(`\s*\(@since:[^)]+\)|\s*\(minimum Coder version:[^)]+\)`)
3030
)
3131

3232
func main() {

0 commit comments

Comments
 (0)
0