This PR implements an inline version metadata system for documenting the minimum Coder version required for resources and features introduced after terraform-provider-coder v2.0.

Implementation

1.Inline Version Metadata

Version requirements are embedded inDescription fields using@since:vX.Y.Z markers
Only resources/features added after terraform-provider-coder v2.0.1 (December 4, 2024) have version markers
No external registry files - version info stays with the code

2.Automated Documentation Generation

Enhancedscripts/docsgen/main.go extracts@since: markers
Adds formatted version notes only to resources with explicit markers
Adds inline*(since vX.Y.Z)* markers to new attributes
No version info shown for resources that existed before provider v2.0

3.Version Compatibility Matrix

Added totemplates/index.md.tmpl
Shows provider versions mapped to minimum Coder versions
Documents major features in each release

Resources with Version Requirements

Only resources/features introduced after terraform-provider-coder v2.0.1 show version requirements:

coder_ai_task - v2.24.0 (added June 19, 2025)
coder_devcontainer - v2.21.0 (added March 20, 2025)
coder_workspace_preset - v2.8.0 (added February 4, 2025)

Note: Thecoder_app.hidden attribute was added in September 2024 (before provider v2.0.1) and therefore does not have a version marker.

Examples

New Resource (added after provider v2.0)

Description: "Define a Dev Container. @since:v2.21.0",

Generates:

~> **Note:** This resource requires [Coder v2.21.0](...) or later.

New Attribute (if added after provider v2.0)

Description: "New feature description. @since:v2.25.0",

Generates:

- `new_feature` (Boolean) New feature description. *(since v2.25.0)*

Key Design Decisions

Provider v2.0 as baseline: Only resources added after terraform-provider-coder v2.0.1 show version requirements
Single format: Uses@since: consistently for both resources and attributes
Explicit markers only: No default versions - only resources with markers show version info
Developer-friendly: Version info lives in the code, making it hard to forget

Testing

✅ Verified resources from before provider v2.0 don't show version requirements
✅ Confirmed new resources (added after provider v2.0) show appropriate version notes
✅ Tested attribute version markers work correctly
✅ Validated documentation generation process

Developer Documentation

provider/VERSION_METADATA.md explains:

When to add version markers (only for features added after terraform-provider-coder v2.0)
How to use the@since: format
Best practices for version documentation

matifali marked this pull request as draft

June 27, 2025 15:12

blink-sobot changed the title~~docs: document minimum Coder version for each resource~~feat: implement automated version documentation system

Jun 27, 2025

blink-sobot changed the title~~feat: implement automated version documentation system~~feat: implement inline version metadata system for documentation

Jun 27, 2025

blink-sobot changed the title~~feat: implement inline version metadata system for documentation~~feat: implement inline version metadata system for new resources

Jun 27, 2025

matifali requested changes

Jun 27, 2025

View reviewed changes

docs/data-sources/workspace_preset.md OutdatedShow resolvedHide resolved

docs/index.md OutdatedShow resolvedHide resolved

docs/resources/ai_task.md OutdatedShow resolvedHide resolved

matifali reviewed

Jun 27, 2025

View reviewed changes

provider/version_meta.go OutdatedShow resolvedHide resolved

matifali reviewed

Jun 27, 2025

View reviewed changes

scripts/docsgen/main.goShow resolvedHide resolved

blink-sobotand others added12 commits

June 27, 2025 18:32

Update coder_ai_task minimum version to v2.24.0

3a273c6

Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>

feat: implement automated version documentation system

2b138af

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>

refactor: implement inline version metadata system

14601f8

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>

refactor: standardize on single@SInCE: version format

898c99d

Simplified the version metadata system to use a single@SInCE: formatfor both resources and attributes, eliminating confusion from havingtwo 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 formatThis makes the system more consistent and easier to use.Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>

refactor: only show version requirements for new resources

c35d3dd

Removed version requirements from resources that existed before Coder v2.0,as these requirements are not meaningful for established resources.Changes:- Updated docsgen to only add version notes when@SInCE: marker is present- Removed default v2.18.0 version assignment- Added@SInCE:v2.8.0 to workspace_preset data source- Updated documentation to clarify when to add version markersNow only resources/features introduced after v2.0 show version requirements:- coder_ai_task (v2.24.0)- coder_devcontainer (v2.21.0)- coder_workspace_preset (v2.8.0)- coder_app.hidden attribute (v2.16.0)Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>

fix: remove@SInCEmarker from hidden attribute (added before provide…

38d3b0e

…r v2.0)The hidden attribute for coder_app was added in September 2024, beforeterraform-provider-coder v2.0.1 was released in December 2024. Onlyresources/features added after provider v2.0 should have@SInCE markers.Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>

docs: regenerate documentation after removing@SInCEmarker

6b0d678

Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>

fix: address review feedback

a6078d3

- Remove version compatibility table from index.md- Clean up ai_task description to remove@SInCE marker- Clean up workspace_preset description to remove@SInCE marker- Regenerate documentationCo-authored-by: matifali <10648092+matifali@users.noreply.github.com>

fix: remove version_meta.go file

98c2d43

Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>

fix: sanitize@SInCEmarkers from generated documentation

2a429aa

- Add cleanVersionMarkers function to remove@SInCE patterns from docs- Apply cleaning in adjustDocFile and processAttributeVersions-@SInCE markers are now only used to extract version info, not displayed- Version notes and inline markers are still added correctlyCo-authored-by: matifali <10648092+matifali@users.noreply.github.com># Conflicts:#docs/resources/script.md

fix: preserve documentation formatting when cleaning@SInCEmarkers

e073cc7

- Fix cleanVersionMarkers to only remove double spaces, not all whitespace- Preserve newlines and YAML frontmatter formatting- Documentation now renders properly formattedCo-authored-by: matifali <10648092+matifali@users.noreply.github.com>

docs: update script.md after rebase

e642c95

Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>

blink-sobotforce-pushed thedocs/minimum-coder-version-272 branch from0a0c26b toe642c95Compare

June 27, 2025 18:34

matifali reviewed

Jun 27, 2025

View reviewed changes

provider/VERSION_METADATA.md Outdated

Comment on lines 91 to 93

		- Add @since: markers for resources introduced after Coder v2.0
		- Add @since: markers for attributes added to existing resources
		- Don't add markers for resources that existed before Coder v2.0

Copy link

Member

matifaliJun 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change

	-Add@since: markers for resources introduced after Coder v2.0
	-Add@since: markers for attributes added to existing resources
	-Don't add markers for resources that existed before Coder v2.0
	-Add@since: markers for newly introduced resources and data sources
	-Add@since: markers for attributes added to existing resources and data sources

matifali reviewed

Jun 27, 2025

View reviewed changes

provider/VERSION_METADATA.md Outdated

Comment on lines 101 to 102

		4. Keep descriptions concise - the version marker is removed from the final docs
		5. Use the version constants from `version_meta.go` when available:

Copy link

Member

matifaliJun 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Suggested change

	4.Keep descriptions concise - the version marker is removed from the final docs
	5.Use the version constants from`version_meta.go` when available:

not needed

matifali reviewed

Jun 27, 2025

View reviewed changes

provider/VERSION_METADATA.md Outdated

Comment on lines 103 to 105

		```go
		Description: "My feature. @since:" + provider.V2_21_0,
		```

Copy link

Member

matifaliJun 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I think this is also not needed now.

docs: update VERSION_METADATA.md per review feedback

83112e6

- Update wording to be more specific about resources and data sources- Remove reference to deleted version_meta.go file- Clarify terraform-provider-coder v2.0 vs Coder v2.0Co-authored-by: matifali <10648092+matifali@users.noreply.github.com>

Labels

None yet

1 participant

	-Add@since: markers for resources introduced after Coder v2.0
	-Add@since: markers for attributes added to existing resources
	-Don't add markers for resources that existed before Coder v2.0
	-Add@since: markers for newly introduced resources and data sources
	-Add@since: markers for attributes added to existing resources and data sources

Movatterモバイル変換

feat: implement inline version metadata system for new resources#417

Are you sure you want to change the base?

feat: implement inline version metadata system for new resources#417

Uh oh!

Conversation

blink-sobot commentedJun 27, 2025• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Implementation

1.Inline Version Metadata

2.Automated Documentation Generation

3.Version Compatibility Matrix

Resources with Version Requirements

Examples

New Resource (added after provider v2.0)

New Attribute (if added after provider v2.0)

Key Design Decisions

Testing

Developer Documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

matifaliJun 27, 2025

Choose a reason for hiding this comment

Uh oh!

matifaliJun 27, 2025

Choose a reason for hiding this comment

Uh oh!

matifaliJun 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

blink-sobot commentedJun 27, 2025•
edited
Loading