feat: implement inline version metadata system for new resources #417
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![blink-so[bot]](https://avatars.githubusercontent.com/in/1271127?s=60&v=4){kind=small}
blink-so
bot
changed the title
blink-so
bot
changed the title
blink-so
bot
changed the title
matifali
requested changes
Jun 27, 2025
matifali
reviewed
Jun 27, 2025
matifali
reviewed
Jun 27, 2025
Co-authored-by: matifali <[email protected]>
Implements a maintainable system for documenting minimum Coder version requirements 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 version This ensures users can easily identify version requirements and prevents compatibility issues. Co-authored-by: matifali <[email protected]>
Refactored the version documentation system to store version requirements directly in resource and attribute descriptions, eliminating the need for an 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 system This approach keeps version information close to the code, making it easier to maintain and harder to forget when adding new features. Co-authored-by: matifali <[email protected]>
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 <[email protected]>
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 markers Now 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 <[email protected]>
…r v2.0) The hidden attribute for coder_app was added in September 2024, before terraform-provider-coder v2.0.1 was released in December 2024. Only resources/features added after provider v2.0 should have @SInCE markers. Co-authored-by: matifali <[email protected]>
Co-authored-by: matifali <[email protected]>
- 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 documentation Co-authored-by: matifali <[email protected]>
Co-authored-by: matifali <[email protected]>
- 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 correctly Co-authored-by: matifali <[email protected]> # Conflicts: # docs/resources/script.md
- Fix cleanVersionMarkers to only remove double spaces, not all whitespace - Preserve newlines and YAML frontmatter formatting - Documentation now renders properly formatted Co-authored-by: matifali <[email protected]>
Co-authored-by: matifali <[email protected]>
blink-so
bot
force-pushed
the
docs/minimum-coder-version-272
branch
from
0a0c26b to
e642c95
Compare
matifali
reviewed
Jun 27, 2025
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 |
There was a problem hiding this comment.
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
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: |
There was a problem hiding this comment.
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
provider/VERSION_METADATA.md
Outdated
Comment on lines
103
to
105
| ```go | ||
| Description: "My feature. @since:" + provider.V2_21_0, | ||
| ``` |
There was a problem hiding this comment.
I think this is also not needed now.
- 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.0 Co-authored-by: matifali <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #272
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
Descriptionfields using@since:vX.Y.Zmarkers2. Automated Documentation Generation
scripts/docsgen/main.goextracts@since:markers*(since vX.Y.Z)*markers to new attributes3. Version Compatibility Matrix
templates/index.md.tmplResources 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: The
coder_app.hiddenattribute 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)
Generates:
New Attribute (if added after provider v2.0)
Generates:
Key Design Decisions
@since:consistently for both resources and attributesTesting
Developer Documentation
provider/VERSION_METADATA.mdexplains:@since:format