Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit14601f8

Browse files
refactor: implement inline version metadata system
Refactored the version documentation system to store version requirementsdirectly in resource and attribute descriptions, eliminating the need foran 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 systemThis approach keeps version information close to the code, making iteasier to maintain and harder to forget when adding new features.Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>
1 parent2b138af commit14601f8

File tree

11 files changed

+265
-115
lines changed

11 files changed

+265
-115
lines changed

‎docs/resources/ai_task.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,12 @@
33
page_title:"coder_ai_task Resource - terraform-provider-coder"
44
subcategory:""
55
description:|-
6-
Use this resource to define Coder tasks.
7-
~> Note: This resource requires Coder v2.24.0 https://github.com/coder/coder/releases/tag/v2.24.0 or later.
6+
Use this resource to define Coder tasks. @minCoderVersion:v2.24.0
87
---
98

109
#coder_ai_task (Resource)
1110

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

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

‎docs/resources/app.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ resource "coder_app" "vim" {
6767
-`external` (Boolean) Specifies whether`url` is opened on the client machine instead of proxied through the workspace.
6868
-`group` (String) The name of a group that this app belongs to.
6969
-`healthcheck` (Block Set, Max: 1) HTTP health checking to determine the application readiness. (see[below for nested schema](#nestedblock--healthcheck))
70-
-`hidden` (Boolean) Determines if the app is visible in the UI (minimum Coder version:v2.16).
70+
-`hidden` (Boolean) Determines if the app is visible in the UI.*(sincev2.16.0)*
7171
-`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>"`.
7272
-`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.
7373
-`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).

‎docs/resources/devcontainer.md

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,15 @@
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.
7-
-> This resource is only available in Coder v2.21 and later.
6+
Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0
87
---
98

109
#coder_devcontainer (Resource)
1110

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

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

16-
-> This resource is only available in Coder v2.21 and later.
17-
1815

1916

2017
<!-- schema generated by tfplugindocs-->

‎provider/RESOURCE_VERSIONS.md

Lines changed: 0 additions & 50 deletions
This file was deleted.

‎provider/VERSION_METADATA.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
#Version Metadata Documentation
2+
3+
This document explains how to add version requirements to resources and attributes in the terraform-provider-coder.
4+
5+
##Overview
6+
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.
8+
9+
##Adding Version Requirements
10+
11+
###For Resources
12+
13+
Add a version marker to the resource's`Description` field:
14+
15+
```go
16+
Description:"Your resource description. @minCoderVersion:v2.21.0",
17+
```
18+
19+
The marker will be automatically removed from the generated docs and replaced with a formatted note.
20+
21+
###For Attributes
22+
23+
Add a version marker to the attribute's`Description` field:
24+
25+
```go
26+
"my_attribute": {
27+
Type: schema.TypeString,
28+
Description:"Attribute description. @since:v2.16.0",
29+
Optional:true,
30+
},
31+
```
32+
33+
This will result in the documentation showing:`- my_attribute (String) Attribute description. *(since v2.16.0)*`
34+
35+
##Version Marker Formats
36+
37+
You can use either format:
38+
-`@minCoderVersion:vX.Y.Z` - For resources
39+
-`@since:vX.Y.Z` - For attributes
40+
41+
Both formats are recognized and processed the same way.
42+
43+
##How It Works
44+
45+
1.**During Development**: Add version markers to descriptions
46+
2.**During Doc Generation**:
47+
-`terraform-plugin-docs` generates initial documentation
48+
- Our custom`docsgen` script:
49+
- Extracts version information from descriptions
50+
- Adds formatted version notes to resources
51+
- Adds inline version markers to attributes
52+
- Cleans up the version patterns from descriptions
53+
54+
##Examples
55+
56+
###Resource Example
57+
58+
```go
59+
funcmyNewResource() *schema.Resource {
60+
return &schema.Resource{
61+
Description:"Manages a new Coder feature. @minCoderVersion:v2.25.0",
62+
// ... rest of resource definition
63+
}
64+
}
65+
```
66+
67+
Results in documentation with:
68+
```markdown
69+
# coder_my_new (Resource)
70+
71+
Manages a new Coder feature.
72+
73+
~> **Note:** This resource requires [Coder v2.25.0](https://github.com/coder/coder/releases/tag/v2.25.0) or later.
74+
```
75+
76+
###Attribute Example
77+
78+
```go
79+
"advanced_option": {
80+
Type: schema.TypeBool,
81+
Description:"Enable advanced features. @since:v2.22.0",
82+
Optional:true,
83+
},
84+
```
85+
86+
Results in documentation with:
87+
```markdown
88+
- `advanced_option` (Boolean) Enable advanced features. *(since v2.22.0)*
89+
```
90+
91+
##Default Versions
92+
93+
- Resources without version markers default to`v2.18.0` (the base requirement)
94+
- Attributes without version markers don't show version information
95+
- Special resources have hardcoded defaults:
96+
-`coder_devcontainer`: v2.21.0
97+
-`coder_ai_task`: v2.24.0
98+
99+
##Best Practices
100+
101+
1.**Always add version markers** when creating new resources or attributes
102+
2.**Use semantic versioning** (vX.Y.Z format)
103+
3.**Test documentation generation** with`make gen` after adding markers
104+
4.**Keep descriptions concise** - the version marker is removed from the final docs

‎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.\n\n~> **Note:** This resource requires [Coderv2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later.",
28+
Description:"Use this resource to define Coder tasks. @minCoderVersion:v2.24.0",
2929
CreateContext:func(c context.Context,resourceData*schema.ResourceData,iany) diag.Diagnostics {
3030
resourceData.SetId(uuid.NewString())
3131
returnnil

‎provider/app.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -251,7 +251,7 @@ func appResource() *schema.Resource {
251251
},
252252
"hidden": {
253253
Type:schema.TypeBool,
254-
Description:"Determines if the app is visible in the UI (minimum Coder version:v2.16).",
254+
Description:"Determines if the app is visible in the UI. @since:v2.16.0",
255255
Default:false,
256256
ForceNew:true,
257257
Optional:true,

‎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.\n\n-> This resource is only available in Coderv2.21 and later.",
16+
Description:"Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0",
1717
CreateContext:func(_ context.Context,rd*schema.ResourceData,_interface{}) diag.Diagnostics {
1818
rd.SetId(uuid.NewString())
1919

‎provider/resource_versions.go

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎provider/version_meta.go

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
package provider
2+
3+
// VersionMeta provides utilities for managing version metadata in resources.
4+
// 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+
funcMinCoderVersion(versionstring)string {
10+
return"@minCoderVersion:"+version
11+
}
12+
13+
// Common version constants for frequently used versions
14+
const (
15+
// V2_18_0 is the base requirement for terraform-provider-coder v2.0+
16+
V2_18_0="v2.18.0"
17+
18+
// V2_16_0 introduced the hidden attribute for apps
19+
V2_16_0="v2.16.0"
20+
21+
// V2_21_0 introduced devcontainer support
22+
V2_21_0="v2.21.0"
23+
24+
// V2_24_0 introduced AI task resources
25+
V2_24_0="v2.24.0"
26+
)

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp