- Notifications
You must be signed in to change notification settings - Fork1k
docs: add contribution documentation for modules and templates#18820
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Merged
Uh oh!
There was an error while loading.Please reload this page.
Merged
Changes fromall commits
Commits
Show all changes
23 commits Select commitHold shift + click to select a range
fb1d650 docs: add contributing guideline docs for modules and templates
DevelopmentCats5238467 docs: move and update detailed contributing guidelines for modules an…
DevelopmentCatsc692a8a docs: update module contribution guidelines and remove redundant content
DevelopmentCatsbd1df6b docs: remove redundant label from registry description
DevelopmentCatsa3bd628 docs: add new sections for contributing modules and templates in the …
DevelopmentCats5a74ceb docs: remove unnecessary whitespace in module contribution guidelines
DevelopmentCatsfbc9837 Merge branch 'main' into cat/contrib-docs
DevelopmentCatsaaa5fe1 Update docs/about/contributing/modules.md
DevelopmentCatsdf66bf2 docs(modules): split ide's into web and desktop with examples
DevelopmentCats38db529 docs(modules): update examples for development tools and workspace ut…
DevelopmentCatsa78c04f docs(modules): update alerts to all match GFM style
DevelopmentCatse280608 docs(modules): simplify version bump instructions in contribution gui…
DevelopmentCats867c60d docs(modules): remove outdated troubleshooting tips from contribution…
DevelopmentCats7cb96d8 docs(modules): remove redundant common issues
DevelopmentCatsd274157 docs(modules): update reference module links in contribution guidelines
DevelopmentCatsc9ddb08 docs(contributing): update all frontmatter fields in both docs and ad…
DevelopmentCats132d499 docs(contributing): remove redundant template issues and remove over …
DevelopmentCatsb9b548d docs(contributing): update examples section with links to official Co…
DevelopmentCats6099665 docs(contributing): update issue reporting instructions to include di…
DevelopmentCatsd998ba4 Merge branch 'main' into cat/contrib-docs
DevelopmentCats2ec825a docs(contributing): update module examples with new versions agent ID…
DevelopmentCatsca4654f docs(contributing): update module examples section to replace 'Develo…
DevelopmentCatsb730042 Merge branch 'main' into cat/contrib-docs
DevelopmentCatsFile filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
386 changes: 386 additions & 0 deletionsdocs/about/contributing/modules.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,386 @@ | ||
| # Contributing modules | ||
| Learn how to create and contribute Terraform modules to the Coder Registry. Modules provide reusable components that extend Coder workspaces with IDEs, development tools, login tools, and other features. | ||
| ## What are Coder modules | ||
| Coder modules are Terraform modules that integrate with Coder workspaces to provide specific functionality. They are published to the Coder Registry at [registry.coder.com](https://registry.coder.com) and can be consumed in any Coder template using standard Terraform module syntax. | ||
| Examples of modules include: | ||
| - **Desktop IDEs**: [`jetbrains-fleet`](https://registry.coder.com/modules/coder/jetbrains-fleet), [`cursor`](https://registry.coder.com/modules/coder/cursor), [`windsurf`](https://registry.coder.com/modules/coder/windsurf), [`zed`](https://registry.coder.com/modules/coder/zed) | ||
| - **Web IDEs**: [`code-server`](https://registry.coder.com/modules/coder/code-server), [`vscode-web`](https://registry.coder.com/modules/coder/vscode-web), [`jupyter-notebook`](https://registry.coder.com/modules/coder/jupyter-notebook), [`jupyter-lab`](https://registry.coder.com/modules/coder/jupyterlab) | ||
| - **Integrations**: [`devcontainers-cli`](https://registry.coder.com/modules/coder/devcontainers-cli), [`vault-github`](https://registry.coder.com/modules/coder/vault-github), [`jfrog-oauth`](https://registry.coder.com/modules/coder/jfrog-oauth), [`jfrog-token`](https://registry.coder.com/modules/coder/jfrog-token) | ||
| - **Workspace utilities**: [`git-clone`](https://registry.coder.com/modules/coder/git-clone), [`dotfiles`](https://registry.coder.com/modules/coder/dotfiles), [`filebrowser`](https://registry.coder.com/modules/coder/filebrowser), [`coder-login`](https://registry.coder.com/modules/coder/coder-login), [`personalize`](https://registry.coder.com/modules/coder/personalize) | ||
| ## Prerequisites | ||
| Before contributing modules, ensure you have: | ||
| - Basic Terraform knowledge | ||
| - [Terraform installed](https://developer.hashicorp.com/terraform/install) | ||
| - [Docker installed](https://docs.docker.com/get-docker/) (for running tests) | ||
| - [Bun installed](https://bun.sh/docs/installation) (for running tests and tooling) | ||
| ## Setup your development environment | ||
| 1. **Fork and clone the repository**: | ||
| ```bash | ||
| git clone https://github.com/your-username/registry.git | ||
| cd registry | ||
| ``` | ||
| 2. **Install dependencies**: | ||
| ```bash | ||
| bun install | ||
| ``` | ||
| 3. **Understand the structure**: | ||
| ```text | ||
| registry/[namespace]/ | ||
| ├── modules/ # Your modules | ||
| ├── .images/ # Namespace avatar and screenshots | ||
| └── README.md # Namespace description | ||
| ``` | ||
| ## Create your first module | ||
| ### 1. Set up your namespace | ||
| If you're a new contributor, create your namespace directory: | ||
| ```bash | ||
| mkdir -p registry/[your-username] | ||
| mkdir -p registry/[your-username]/.images | ||
| ``` | ||
| Add your namespace avatar by downloading your GitHub avatar and saving it as `avatar.png`: | ||
| ```bash | ||
| curl -o registry/[your-username]/.images/avatar.png https://github.com/[your-username].png | ||
| ``` | ||
| Create your namespace README at `registry/[your-username]/README.md`: | ||
| ```markdown | ||
| --- | ||
| display_name: "Your Name" | ||
| bio: "Brief description of what you do" | ||
| github: "your-username" | ||
| avatar: "./.images/avatar.png" | ||
| linkedin: "https://www.linkedin.com/in/your-username" | ||
| website: "https://your-website.com" | ||
| support_email: "support@your-domain.com" | ||
| status: "community" | ||
| --- | ||
| # Your Name | ||
| Brief description of who you are and what you do. | ||
| ``` | ||
| > [!NOTE] | ||
| > The `linkedin`, `website`, and `support_email` fields are optional and can be omitted or left empty if not applicable. | ||
| ### 2. Generate module scaffolding | ||
| Use the provided script to generate your module structure: | ||
| ```bash | ||
| ./scripts/new_module.sh [your-username]/[module-name] | ||
| cd registry/[your-username]/modules/[module-name] | ||
| ``` | ||
| This creates: | ||
| - `main.tf` - Terraform configuration template | ||
| - `README.md` - Documentation template with frontmatter | ||
| - `run.sh` - Optional execution script | ||
| ### 3. Implement your module | ||
| Edit `main.tf` to build your module's features. Here's an example based on the `git-clone` module structure: | ||
| ```terraform | ||
| terraform { | ||
| required_providers { | ||
| coder = { | ||
| source = "coder/coder" | ||
| } | ||
| } | ||
| } | ||
| # Input variables | ||
| variable "agent_id" { | ||
| description = "The ID of a Coder agent" | ||
| type = string | ||
| } | ||
| variable "url" { | ||
| description = "Git repository URL to clone" | ||
| type = string | ||
| validation { | ||
| condition = can(regex("^(https?://|git@)", var.url)) | ||
| error_message = "URL must be a valid git repository URL." | ||
| } | ||
| } | ||
| variable "base_dir" { | ||
| description = "Directory to clone the repository into" | ||
| type = string | ||
| default = "~" | ||
| } | ||
| # Resources | ||
| resource "coder_script" "clone_repo" { | ||
| agent_id = var.agent_id | ||
| display_name = "Clone Repository" | ||
| script = <<-EOT | ||
| #!/bin/bash | ||
| set -e | ||
| # Ensure git is installed | ||
| if ! command -v git &> /dev/null; then | ||
| echo "Installing git..." | ||
| sudo apt-get update && sudo apt-get install -y git | ||
| fi | ||
| # Clone repository if it doesn't exist | ||
| if [ ! -d "${var.base_dir}/$(basename ${var.url} .git)" ]; then | ||
| echo "Cloning ${var.url}..." | ||
| git clone ${var.url} ${var.base_dir}/$(basename ${var.url} .git) | ||
| fi | ||
| EOT | ||
| run_on_start = true | ||
| } | ||
| # Outputs | ||
| output "repo_dir" { | ||
| description = "Path to the cloned repository" | ||
| value = "${var.base_dir}/$(basename ${var.url} .git)" | ||
| } | ||
| ``` | ||
| ### 4. Write complete tests | ||
| Create `main.test.ts` to test your module features: | ||
| ```typescript | ||
| import { runTerraformApply, runTerraformInit, testRequiredVariables } from "~test" | ||
| describe("git-clone", async () => { | ||
| await testRequiredVariables("registry/[your-username]/modules/git-clone") | ||
| it("should clone repository successfully", async () => { | ||
| await runTerraformInit("registry/[your-username]/modules/git-clone") | ||
| await runTerraformApply("registry/[your-username]/modules/git-clone", { | ||
| agent_id: "test-agent-id", | ||
| url: "https://github.com/coder/coder.git", | ||
| base_dir: "/tmp" | ||
| }) | ||
| }) | ||
| it("should work with SSH URLs", async () => { | ||
| await runTerraformInit("registry/[your-username]/modules/git-clone") | ||
| await runTerraformApply("registry/[your-username]/modules/git-clone", { | ||
| agent_id: "test-agent-id", | ||
| url: "git@github.com:coder/coder.git" | ||
| }) | ||
| }) | ||
| }) | ||
| ``` | ||
| ### 5. Document your module | ||
| Update `README.md` with complete documentation: | ||
| ```markdown | ||
| --- | ||
| display_name: "Git Clone" | ||
| description: "Clone a Git repository into your Coder workspace" | ||
| icon: "../../../../.icons/git.svg" | ||
| verified: false | ||
| tags: ["git", "development", "vcs"] | ||
| --- | ||
| # Git Clone | ||
| This module clones a Git repository into your Coder workspace and ensures Git is installed. | ||
| ## Usage | ||
| ```tf | ||
| module "git_clone" { | ||
| source = "registry.coder.com/[your-username]/git-clone/coder" | ||
| version = "~> 1.0" | ||
| agent_id = coder_agent.main.id | ||
| url = "https://github.com/coder/coder.git" | ||
| base_dir = "/home/coder/projects" | ||
| } | ||
| ``` | ||
| ## Module best practices | ||
| ### Design principles | ||
| - **Single responsibility**: Each module should have one clear purpose | ||
| - **Reusability**: Design for use across different workspace types | ||
| - **Flexibility**: Provide sensible defaults but allow customization | ||
| - **Safe to rerun**: Ensure modules can be applied multiple times safely | ||
| ### Terraform conventions | ||
| - Use descriptive variable names and include descriptions | ||
| - Provide default values for optional variables | ||
| - Include helpful outputs for working with other modules | ||
| - Use proper resource dependencies | ||
| - Follow [Terraform style conventions](https://developer.hashicorp.com/terraform/language/syntax/style) | ||
| ### Documentation standards | ||
| Your module README should include: | ||
| - **Frontmatter**: Required metadata for the registry | ||
| - **Description**: Clear explanation of what the module does | ||
| - **Usage example**: Working Terraform code snippet | ||
| - **Additional context**: Setup requirements, known limitations, etc. | ||
| > [!NOTE] | ||
| > Do not include variables tables in your README. The registry automatically generates variable documentation from your `main.tf` file. | ||
| ## Test your module | ||
| Run tests to ensure your module works correctly: | ||
| ```bash | ||
| # Test your specific module | ||
| bun test -t 'git-clone' | ||
DevelopmentCats marked this conversation as resolved. Show resolvedHide resolvedUh oh!There was an error while loading.Please reload this page. | ||
| # Test all modules | ||
| bun test | ||
| # Format code | ||
| bun fmt | ||
| ``` | ||
| > [!IMPORTANT] | ||
| > Tests require Docker with `--network=host` support, which typically requires Linux. macOS users can use [Colima](https://github.com/abiosoft/colima) or [OrbStack](https://orbstack.dev/) instead of Docker Desktop. | ||
| ## Contribute to existing modules | ||
| ### Types of contributions | ||
| **Bug fixes**: | ||
| - Fix installation or configuration issues | ||
| - Resolve compatibility problems | ||
| - Correct documentation errors | ||
| **Feature additions**: | ||
| - Add new configuration options | ||
| - Support additional platforms or versions | ||
| - Add new features | ||
| **Maintenance**: | ||
| - Update dependencies | ||
| - Improve error handling | ||
| - Optimize performance | ||
| ### Making changes | ||
| 1. **Identify the issue**: Reproduce the problem or identify the improvement needed | ||
| 2. **Make focused changes**: Keep modifications minimal and targeted | ||
| 3. **Maintain compatibility**: Ensure existing users aren't broken | ||
| 4. **Add tests**: Test new features and edge cases | ||
| 5. **Update documentation**: Reflect changes in the README | ||
| ### Backward compatibility | ||
| When modifying existing modules: | ||
| - Add new variables with sensible defaults | ||
| - Don't remove existing variables without a migration path | ||
| - Don't change variable types or meanings | ||
| - Test that basic configurations still work | ||
| ## Versioning | ||
| When you modify a module, update its version following semantic versioning: | ||
| - **Patch** (1.0.0 → 1.0.1): Bug fixes, documentation updates | ||
| - **Minor** (1.0.0 → 1.1.0): New features, new variables | ||
| - **Major** (1.0.0 → 2.0.0): Breaking changes, removing variables | ||
| Use the version bump script to update versions: | ||
| ```bash | ||
| ./.github/scripts/version-bump.sh patch|minor|major | ||
| ``` | ||
| ## Submit your contribution | ||
| 1. **Create a feature branch**: | ||
| ```bash | ||
| git checkout -b feat/modify-git-clone-module | ||
| ``` | ||
| 2. **Test thoroughly**: | ||
| ```bash | ||
| bun test -t 'git-clone' | ||
matifali marked this conversation as resolved. Show resolvedHide resolvedUh oh!There was an error while loading.Please reload this page. | ||
| bun fmt | ||
| ``` | ||
| 3. **Commit with clear messages**: | ||
| ```bash | ||
| git add . | ||
| git commit -m "feat(git-clone):add git-clone module" | ||
| ``` | ||
| 4. **Open a pull request**: | ||
| - Use a descriptive title | ||
| - Explain what the module does and why it's useful | ||
| - Reference any related issues | ||
| ## Common issues and solutions | ||
| ### Testing problems | ||
| **Issue**: Tests fail with network errors | ||
| **Solution**: Ensure Docker is running with `--network=host` support | ||
DevelopmentCats marked this conversation as resolved. Show resolvedHide resolvedUh oh!There was an error while loading.Please reload this page. | ||
| ### Module development | ||
| **Issue**: Icon not displaying | ||
| **Solution**: Verify icon path is correct and file exists in `.icons/` directory | ||
| ### Documentation | ||
| **Issue**: Code blocks not syntax highlighted | ||
| **Solution**: Use `tf` language identifier for Terraform code blocks | ||
| ## Get help | ||
| - **Examples**: Review existing modules like [`code-server`](https://registry.coder.com/modules/coder/code-server), [`git-clone`](https://registry.coder.com/modules/coder/git-clone), and [`jetbrains-gateway`](https://registry.coder.com/modules/coder/jetbrains-gateway) | ||
| - **Issues**: Open an issue at [github.com/coder/registry](https://github.com/coder/registry/issues) | ||
| - **Community**: Join the [Coder Discord](https://discord.gg/coder) for questions | ||
| - **Documentation**: Check the [Coder docs](https://coder.com/docs) for help on Coder. | ||
| ## Next steps | ||
| After creating your first module: | ||
| 1. **Share with the community**: Announce your module on Discord or social media | ||
| 2. **Iterate based on feedback**: Improve based on user suggestions | ||
| 3. **Create more modules**: Build a collection of related tools | ||
| 4. **Contribute to existing modules**: Help maintain and improve the ecosystem | ||
| Happy contributing! 🚀 | ||
Oops, something went wrong.
Uh oh!
There was an error while loading.Please reload this page.
Oops, something went wrong.
Uh oh!
There was an error while loading.Please reload this page.
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.