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

Commit2b138af

Browse files
feat: implement automated version documentation system
Implements a maintainable system for documenting minimum Coder versionrequirements 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 versionThis ensures users can easily identify version requirements and preventscompatibility issues.Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>
1 parent3a273c6 commit2b138af

19 files changed

+239
-1
lines changed

‎docs/data-sources/external_auth.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
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.)
1212

13+
~>**Note:** This data source requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/data-sources/parameter.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
Use this data source to configure editable options for workspaces.
1212

13+
~>**Note:** This data source requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/data-sources/provisioner.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
Use this data source to get information about the Coder provisioner.
1212

13+
~>**Note:** This data source requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/data-sources/workspace.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
Use this data source to get information for the active workspace build.
1212

13+
~>**Note:** This data source requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/data-sources/workspace_owner.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
Use this data source to fetch information about the workspace owner.
1212

13+
~>**Note:** This data source requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/data-sources/workspace_preset.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
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.
1212

13+
~>**Note:** This data source requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/data-sources/workspace_tags.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
Use this data source to configure workspace tags to select provisioners.
1212

13+
~>**Note:** This data source requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/index.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,20 @@ Terraform provider for managing Coder [templates](https://coder.com/docs/admin/t
1414

1515
!>[`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.
1616

17+
##Version Compatibility
18+
19+
The following table shows the minimum Coder version required for each terraform-provider-coder release:
20+
21+
| Provider Version| Minimum Coder Version| Key Features|
22+
|------------------|-----------------------|--------------|
23+
| v2.8.0+|[v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0)| Default preset support|
24+
| v2.7.0+|[v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0)| AI task resource|
25+
| v2.6.0+|[v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0)| Scheduling configuration for prebuilds|
26+
| v2.5.0+|[v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0)| Devcontainer support|
27+
| v2.0.0+|[v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0)| Base requirement for v2 provider|
28+
29+
~>**Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version.
30+
1731
##Example
1832

1933
```terraform

‎docs/resources/agent.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
Use this resource to associate an agent.
1212

13+
~>**Note:** This resource requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/resources/agent_instance.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
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.
1212

13+
~>**Note:** This resource requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/resources/app.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
Use this resource to define shortcuts to access applications in a workspace.
1212

13+
~>**Note:** This resource requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/resources/devcontainer.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ description: |-
1111

1212
Define a Dev Container the agent should know of and attempt to autostart.
1313

14+
~>**Note:** This resource requires[Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later.
15+
1416
-> This resource is only available in Coder v2.21 and later.
1517

1618

‎docs/resources/env.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
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.
1212

13+
~>**Note:** This resource requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎docs/resources/metadata.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ description: |-
1111

1212
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.
1313

14+
~>**Note:** This resource requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
15+
1416
Alternatively, to attach metadata to the agent, use a`metadata` block within a`coder_agent` resource.
1517

1618
##Example Usage

‎docs/resources/script.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel.
1212

13+
~>**Note:** This resource requires[Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later.
14+
1315
##Example Usage
1416

1517
```terraform

‎provider/RESOURCE_VERSIONS.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
#Resource Version Requirements
2+
3+
This document explains how to maintain version requirements for terraform-provider-coder resources.
4+
5+
##Overview
6+
7+
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.
8+
9+
##Adding a New Resource
10+
11+
When adding a new resource or data source, you MUST:
12+
13+
1. Add an entry to the`ResourceVersions` map in`resource_versions.go`
14+
2. Set the minimum Coder version that supports this resource
15+
3. Run`make gen` to regenerate the documentation
16+
17+
###Example
18+
19+
```go
20+
varResourceVersions =map[string]string{
21+
// ... existing entries ...
22+
"coder_new_resource":"v2.25.0",// Add your new resource here
23+
}
24+
```
25+
26+
##Version Guidelines
27+
28+
-**Default minimum**: v2.18.0 (the base requirement for terraform-provider-coder v2.0+)
29+
-**New features**: Use the Coder version where the feature was first introduced
30+
-**Attribute-level requirements**: Use the`AttributeVersions` map for attributes added after the resource itself
31+
32+
##How It Works
33+
34+
1.`terraform-plugin-docs` generates the initial documentation
35+
2. Our custom`docsgen` script reads the version registry
36+
3. Version notes are automatically added to each resource's documentation
37+
4. The version compatibility matrix in`index.md` is maintained manually in the template
38+
39+
##Testing
40+
41+
After adding or updating version information:
42+
43+
1. Run`make gen`
44+
2. Check that the generated docs include the version note
45+
3. Verify the note appears after the resource description
46+
47+
##Common Issues
48+
49+
-**Missing version error**: If you see "no version information found", add the resource to`ResourceVersions`
50+
-**Duplicate notes**: If a resource already has version info in its Description, remove it and rely on the registry

‎provider/resource_versions.go

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
package provider
2+
3+
// ResourceVersions maps each resource and data source to its minimum required Coder version.
4+
// IMPORTANT: When adding a new resource or data source, you MUST add an entry here!
5+
// This ensures proper documentation of version requirements for users.
6+
varResourceVersions=map[string]string{
7+
// Resources
8+
"coder_agent":"v2.18.0",// Base requirement for terraform-provider-coder v2.0+
9+
"coder_agent_instance":"v2.18.0",
10+
"coder_ai_task":"v2.24.0",// AI features introduced in v2.24.0
11+
"coder_app":"v2.18.0",
12+
"coder_devcontainer":"v2.21.0",// Devcontainer support added in v2.21.0
13+
"coder_env":"v2.18.0",
14+
"coder_metadata":"v2.18.0",
15+
"coder_script":"v2.18.0",
16+
17+
// Data Sources
18+
"coder_external_auth":"v2.18.0",
19+
"coder_parameter":"v2.18.0",
20+
"coder_provisioner":"v2.18.0",
21+
"coder_workspace":"v2.18.0",
22+
"coder_workspace_owner":"v2.18.0",
23+
"coder_workspace_preset":"v2.18.0",
24+
"coder_workspace_tags":"v2.18.0",
25+
}
26+
27+
// AttributeVersions maps specific resource attributes to their minimum required Coder version.
28+
// Use this for attributes that were added after the resource itself.
29+
varAttributeVersions=map[string]map[string]string{
30+
"coder_app": {
31+
"hidden":"v2.16.0",// Hidden attribute added in v2.16.0
32+
},
33+
}

‎scripts/docsgen/main.go

Lines changed: 100 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,9 @@ import (
1414
"golang.org/x/xerrors"
1515
)
1616

17-
// This script patches Markdown docs generated by `terraform-plugin-docs` to expose the original deprecation message.
17+
// This script patches Markdown docs generated by `terraform-plugin-docs` to:
18+
// 1. Expose the original deprecation message
19+
// 2. Add minimum Coder version requirements
1820

1921
constdocsDir="docs"// FIXME expose as flag?
2022

@@ -26,6 +28,12 @@ func main() {
2628
iferr!=nil {
2729
log.Fatal(err)
2830
}
31+
32+
// Add version information to all resources and data sources
33+
err=addVersionInformation(p)
34+
iferr!=nil {
35+
log.Fatal(err)
36+
}
2937
}
3038

3139
funcexposeDeprecationMessage(p*schema.Provider)error {
@@ -87,3 +95,94 @@ func writeDeprecationMessage(doc []byte, schemas map[string]*schema.Schema) []by
8795
returnbytes.Replace(m, []byte("Deprecated"), []byte(fmt.Sprintf("**Deprecated**: %s",sch.Deprecated)),1)
8896
})
8997
}
98+
99+
funcaddVersionInformation(p*schema.Provider)error {
100+
// Add version info to data sources
101+
fordataSourceName:=rangep.DataSourcesMap {
102+
docFile:=filepath.Join(docsDir,"data-sources",strings.Replace(dataSourceName,"coder_","",1)+".md")
103+
iferr:=addVersionToDoc(docFile,dataSourceName);err!=nil {
104+
returnxerrors.Errorf("unable to add version to data-source doc file (data-source: %s): %w",dataSourceName,err)
105+
}
106+
}
107+
108+
// Add version info to resources
109+
forresourceName:=rangep.ResourcesMap {
110+
docFile:=filepath.Join(docsDir,"resources",strings.Replace(resourceName,"coder_","",1)+".md")
111+
iferr:=addVersionToDoc(docFile,resourceName);err!=nil {
112+
returnxerrors.Errorf("unable to add version to resource doc file (resource: %s): %w",resourceName,err)
113+
}
114+
}
115+
116+
returnnil
117+
}
118+
119+
funcaddVersionToDoc(docPathstring,resourceNamestring)error {
120+
version,ok:=provider.ResourceVersions[resourceName]
121+
if!ok {
122+
returnxerrors.Errorf("no version information found for %s. Please add it to provider.ResourceVersions",resourceName)
123+
}
124+
125+
doc,err:=os.ReadFile(docPath)
126+
iferr!=nil {
127+
returnxerrors.Errorf("can't read the doc file: %w",err)
128+
}
129+
130+
docStr:=string(doc)
131+
132+
// Check if version note already exists
133+
ifstrings.Contains(docStr,"~> **Note:** This")&&strings.Contains(docStr,"requires")&&strings.Contains(docStr,"Coder") {
134+
// Version note already exists, skip
135+
returnnil
136+
}
137+
138+
// Add version note after the description
139+
versionNote:=fmt.Sprintf("\n\n~> **Note:** This %s requires [Coder %s](https://github.com/coder/coder/releases/tag/%s) or later.",
140+
getResourceType(resourceName),version,version)
141+
142+
// Find the end of frontmatter
143+
frontmatterEnd:=-1
144+
lines:=strings.Split(docStr,"\n")
145+
146+
iflen(lines)>0&&lines[0]=="---" {
147+
fori:=1;i<len(lines);i++ {
148+
iflines[i]=="---" {
149+
frontmatterEnd=i
150+
break
151+
}
152+
}
153+
}
154+
155+
// Find where to insert the version note
156+
inserted:=false
157+
fori:=frontmatterEnd+1;i<len(lines);i++ {
158+
// Skip empty lines and headings
159+
iflines[i]==""||strings.HasPrefix(lines[i],"#") {
160+
continue
161+
}
162+
163+
// Insert after the first paragraph (non-empty, non-heading line)
164+
lines[i]=lines[i]+versionNote
165+
inserted=true
166+
break
167+
}
168+
169+
if!inserted {
170+
// If we couldn't find a good place, add it at the end
171+
lines=append(lines,versionNote)
172+
}
173+
174+
docStr=strings.Join(lines,"\n")
175+
176+
err=os.WriteFile(docPath, []byte(docStr),0644)
177+
iferr!=nil {
178+
returnxerrors.Errorf("can't write modified doc file: %w",err)
179+
}
180+
returnnil
181+
}
182+
183+
funcgetResourceType(namestring)string {
184+
ifstrings.Contains(name,"data_source")||strings.Contains(name,"workspace")||strings.Contains(name,"provisioner")||strings.Contains(name,"parameter")||strings.Contains(name,"external_auth") {
185+
return"data source"
186+
}
187+
return"resource"
188+
}

‎templates/index.md.tmpl

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,20 @@ Terraform provider for managing Coder [templates](https://coder.com/docs/admin/t
1414

1515
!> [`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.
1616

17+
## Version Compatibility
18+
19+
The following table shows the minimum Coder version required for each terraform-provider-coder release:
20+
21+
| Provider Version | Minimum Coder Version | Key Features |
22+
|------------------|-----------------------|--------------|
23+
| v2.8.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Default preset support |
24+
| v2.7.0+ | [v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) | AI task resource |
25+
| v2.6.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Scheduling configuration for prebuilds |
26+
| v2.5.0+ | [v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) | Devcontainer support |
27+
| v2.0.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Base requirement for v2 provider |
28+
29+
~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version.
30+
1731
## Example
1832

1933
{{tffile "examples/provider/provider.tf"}}

0 commit comments

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