From 08a92c24cbed01ee07966d950c6101760e994531 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Fri, 4 Jul 2025 03:04:49 +0000 Subject: [PATCH 1/5] docs(CONTRIBUTING): add template contributing guide for new and existing templates --- CONTRIBUTING.md | 203 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 194 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d63b42d..18cff0bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,12 +4,14 @@ Welcome! This guide covers how to contribute to the Coder Registry, whether you' ## What is the Coder Registry? -The Coder Registry is a collection of Terraform modules that extend Coder workspaces with development tools like VS Code, Cursor, JetBrains IDEs, and more. +The Coder Registry is a collection of Terraform modules and templates for Coder workspaces. Modules provide IDEs, authentication integrations, development tools, and other workspace functionality. Templates provide complete workspace configurations for different platforms and use cases that appear as community templates on the registry website. ## Types of Contributions - **[New Modules](#creating-a-new-module)** - Add support for a new tool or functionality +- **[New Templates](#creating-a-new-template)** - Create complete workspace configurations - **[Existing Modules](#contributing-to-existing-modules)** - Fix bugs, add features, or improve documentation +- **[Existing Templates](#contributing-to-existing-templates)** - Improve workspace templates - **[Bug Reports](#reporting-issues)** - Report problems or request features ## Setup @@ -36,7 +38,15 @@ bun install ### Understanding Namespaces -All modules are organized under `/registry/[namespace]/modules/`. Each contributor gets their own namespace (e.g., `/registry/your-username/modules/`). If a namespace is taken, choose a different unique namespace, but you can still use any display name on the Registry website. +All modules and templates are organized under `/registry/[namespace]/`. Each contributor gets their own namespace with both modules and templates directories: + +``` +registry/[namespace]/ +├── modules/ # Individual components and tools +└── templates/ # Complete workspace configurations +``` + +For example: `/registry/your-username/modules/` and `/registry/your-username/templates/`. If a namespace is taken, choose a different unique namespace, but you can still use any display name on the Registry website. ### Images and Icons @@ -136,15 +146,182 @@ git push origin your-branch --- -## Contributing to Existing Modules +## Creating a New Template + +Templates are complete Coder workspace configurations that users can deploy directly. Unlike modules (which are components), templates provide full infrastructure definitions for specific platforms or use cases. + +### Template Structure + +Templates follow the same namespace structure as modules but are located in the `templates` directory: -### 1. Find the Module +``` +registry/[your-username]/templates/[template-name]/ +├── main.tf # Complete Terraform configuration +├── README.md # Documentation with frontmatter +├── [additional files] # Scripts, configs, etc. +``` + +### 1. Create Your Template Directory ```bash -find registry -name "*[module-name]*" -type d +mkdir -p registry/[your-username]/templates/[template-name] +cd registry/[your-username]/templates/[template-name] +``` + +### 2. Create Template Files + +#### main.tf + +Your `main.tf` should be a complete Coder template configuration including: + +- Required providers (coder, and your infrastructure provider) +- Coder agent configuration +- Infrastructure resources (containers, VMs, etc.) +- Registry modules for IDEs, tools, and integrations + +Example structure: + +```terraform +terraform { + required_providers { + coder = { + source = "coder/coder" + } + # Add your infrastructure provider (docker, aws, etc.) + } +} + +# Coder data sources +data "coder_workspace" "me" {} +data "coder_workspace_owner" "me" {} + +# Coder agent +resource "coder_agent" "main" { + arch = "amd64" + os = "linux" + startup_script = <<-EOT + # Startup commands here + EOT +} + +# Registry modules for IDEs, tools, and integrations +module "code-server" { + source = "registry.coder.com/coder/code-server/coder" + version = "~> 1.0" + agent_id = coder_agent.main.id +} + +# Your infrastructure resources +# (Docker containers, AWS instances, etc.) +``` + +#### README.md + +Create comprehensive documentation with proper frontmatter: + +```markdown +--- +display_name: "Template Name" +description: "Brief description of what this template provides" +icon: "../../../../.icons/platform.svg" +maintainer_github: "your-username" +verified: false +tags: ["platform", "use-case", "tools"] +--- + +# Template Name + +Detailed description of the template and what it provisions. + +## Prerequisites + +List any requirements (infrastructure, permissions, etc.) + +## Architecture + +Describe what resources are created and how they work together. + +## Variables + +Document any input variables users can customize. + +## Usage + +Provide clear examples of how to use the template. ``` -### 2. Make Your Changes +### 3. Test Your Template + +Templates should be tested to ensure they work correctly. Test with Coder: + +```bash +cd registry/[your-username]/templates/[template-name] +coder templates push [template-name] -d . +``` + +### 4. Template Best Practices + +- **Use registry modules**: Leverage existing modules for IDEs, tools, and integrations +- **Provide sensible defaults**: Make the template work out-of-the-box +- **Include metadata**: Add useful workspace metadata (CPU, memory, disk usage) +- **Document prerequisites**: Clearly explain infrastructure requirements +- **Use variables**: Allow customization of common settings +- **Follow naming conventions**: Use descriptive, consistent naming + +### 5. Template Guidelines + +- Templates appear as "Community Templates" on the registry website +- Include proper error handling and validation +- Test with Coder before submitting +- Document any required permissions or setup steps +- Use semantic versioning in your README frontmatter + +--- + +## Contributing to Existing Templates + +### 1. Types of Template Improvements + +**Bug fixes:** +- Fix infrastructure provisioning issues +- Resolve agent connectivity problems +- Correct resource naming or tagging + +**Feature additions:** +- Add new registry modules for additional functionality +- Include additional infrastructure options +- Improve startup scripts or automation + +**Platform updates:** +- Update base images or AMIs +- Adapt to new platform features +- Improve security configurations + +**Documentation:** +- Clarify prerequisites and setup steps +- Add troubleshooting guides +- Improve usage examples + +### 2. Testing Template Changes + +Testing template modifications thoroughly is necessary. Test with Coder: + +```bash +coder templates push test-[template-name] -d . +``` + +### 3. Maintain Compatibility + +- Don't remove existing variables without clear migration path +- Preserve backward compatibility when possible +- Test that existing workspaces still function +- Document any breaking changes clearly + +--- + +## Contributing to Existing Modules + +### 1. Make Your Changes **For bug fixes:** @@ -166,7 +343,7 @@ find registry -name "*[module-name]*" -type d - Add missing variable documentation - Improve usage examples -### 3. Test Your Changes +### 2. Test Your Changes ```bash # Test a specific module @@ -176,7 +353,7 @@ bun test -t 'module-name' bun test ``` -### 4. Maintain Backward Compatibility +### 3. Maintain Backward Compatibility - New variables should have default values - Don't break existing functionality @@ -208,6 +385,7 @@ bun test We have different PR templates for different types of contributions. GitHub will show you options to choose from, or you can manually select: - **New Module**: Use `?template=new_module.md` +- **New Template**: Use `?template=new_template.md` - **Bug Fix**: Use `?template=bug_fix.md` - **Feature**: Use `?template=feature.md` - **Documentation**: Use `?template=documentation.md` @@ -224,6 +402,13 @@ Example: `https://github.com/coder/registry/compare/main...your-branch?template= - `main.test.ts` - Working tests - `README.md` - Documentation with frontmatter +### Every Template Must Have + +- `main.tf` - Complete Terraform configuration +- `README.md` - Documentation with frontmatter + +Templates don't require test files like modules do, but should be manually tested before submission. + ### README Frontmatter Module README frontmatter must include: @@ -304,7 +489,7 @@ When reporting bugs, include: ## Getting Help -- **Examples**: Check `/registry/coder/modules/` for well-structured modules +- **Examples**: Check `/registry/coder/modules/` for well-structured modules and `/registry/coder/templates/` for complete templates - **Issues**: Open an issue for technical problems - **Community**: Reach out to the Coder community for questions From 77d136ed9310df42a65addfa63774ebd1e4f8190 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Fri, 4 Jul 2025 22:39:18 +0000 Subject: [PATCH 2/5] docs(CONTRIBUTING): refine template documentation fofor template README --- CONTRIBUTING.md | 20 +++----------------- 1 file changed, 3 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18cff0bf..e809ff5f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -217,7 +217,7 @@ module "code-server" { #### README.md -Create comprehensive documentation with proper frontmatter: +Create documentation with proper frontmatter: ```markdown --- @@ -231,23 +231,9 @@ tags: ["platform", "use-case", "tools"] # Template Name -Detailed description of the template and what it provisions. +Describe what the template provides and how to use it. -## Prerequisites - -List any requirements (infrastructure, permissions, etc.) - -## Architecture - -Describe what resources are created and how they work together. - -## Variables - -Document any input variables users can customize. - -## Usage - -Provide clear examples of how to use the template. +Include any setup requirements, resource information, or usage notes that users need to know. ``` ### 3. Test Your Template From 6b264128854caed194927dfdee66a4ef2656a42d Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Fri, 4 Jul 2025 22:41:20 +0000 Subject: [PATCH 3/5] docs(CONTRIBUTING): bun fmt --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e809ff5f..5428e924 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -269,21 +269,25 @@ coder templates push [template-name] -d . ### 1. Types of Template Improvements **Bug fixes:** + - Fix infrastructure provisioning issues - Resolve agent connectivity problems - Correct resource naming or tagging **Feature additions:** + - Add new registry modules for additional functionality - Include additional infrastructure options - Improve startup scripts or automation **Platform updates:** + - Update base images or AMIs - Adapt to new platform features - Improve security configurations **Documentation:** + - Clarify prerequisites and setup steps - Add troubleshooting guides - Improve usage examples From 0755e6af0c1b31f0044ccdf7508f374d9082273f Mon Sep 17 00:00:00 2001 From: DevCats Date: Mon, 7 Jul 2025 21:41:08 -0500 Subject: [PATCH 4/5] chore: remove maintainer_github from frontmatter Co-authored-by: Atif Ali --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5428e924..087c227b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -224,7 +224,6 @@ Create documentation with proper frontmatter: display_name: "Template Name" description: "Brief description of what this template provides" icon: "../../../../.icons/platform.svg" -maintainer_github: "your-username" verified: false tags: ["platform", "use-case", "tools"] --- From e2e0d6995371d8744f928eed71cd0e4f07fe6027 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Tue, 8 Jul 2025 02:50:19 +0000 Subject: [PATCH 5/5] chore: bun fmt --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 087c227b..3b2b4d1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -197,8 +197,8 @@ data "coder_workspace_owner" "me" {} # Coder agent resource "coder_agent" "main" { - arch = "amd64" - os = "linux" + arch = "amd64" + os = "linux" startup_script = <<-EOT # Startup commands here EOT @@ -206,8 +206,8 @@ resource "coder_agent" "main" { # Registry modules for IDEs, tools, and integrations module "code-server" { - source = "registry.coder.com/coder/code-server/coder" - version = "~> 1.0" + source = "registry.coder.com/coder/code-server/coder" + version = "~> 1.0" agent_id = coder_agent.main.id }