From 11baccd2812a2a74d8d3f4538dfe3b6da7467125 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Wed, 28 May 2025 01:53:33 +0000 Subject: [PATCH 01/26] docs(CONTRIBUTING): remove maintainer instructions, and improve contributing documentation. --- CONTRIBUTING.md | 446 +++++++++++++++++++++++++++--------------------- 1 file changed, 250 insertions(+), 196 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2b990ce7..d306bde1a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,294 +1,348 @@ -# Contributing +# Contributing to the Coder Registry -## Getting started +Welcome! This guide covers how to contribute to the Coder Registry, whether you're creating a new module or improving an existing one. -This repo uses two main runtimes to verify the correctness of a module/template before it is published: +## What is the Coder Registry? -- [Bun](https://bun.sh/) – Used to run tests for each module/template to validate overall functionality and correctness of Terraform output -- [Go](https://go.dev/) – Used to validate all README files in the directory. The README content is used to populate [the Registry website](https://registry.coder.com). +The Coder Registry is a collection of Terraform modules that extend Coder workspaces with development tools like VS Code, Cursor, JetBrains IDEs, and more. -### Installing Bun +## Types of Contributions -To install Bun, you can run this command on Linux/MacOS: +- **[New Modules](#creating-a-new-module)** - Add support for a new tool or functionality +- **[Existing Modules](#contributing-to-existing-modules)** - Fix bugs, add features, or improve documentation +- **[Bug Reports](#reporting-issues)** - Report problems or request features -```shell -curl -fsSL https://bun.sh/install | bash -``` - -Or this command on Windows: - -```shell -powershell -c "irm bun.sh/install.ps1 | iex" -``` - -Follow the instructions to ensure that Bun is available globally. Once Bun is installed, install all necessary dependencies from the root of the repo: +## Setup -Via NPM: +### Prerequisites +- Git and GitHub account +- Basic Terraform knowledge (for module development) +- Docker (for running tests) -```shell -npm i -``` - -Via PNPM: +### Install Dependencies +```bash +# Install Bun (test runner) +curl -fsSL https://bun.sh/install | bash +source ~/.bashrc -```shell -pnpm i +# Install project dependencies +bun install ``` -This repo does not support Yarn. +> **Note**: This repository does not support Yarn. Please use Bun for all package management. -### Installing Go (optional) +### Installing Go (Optional) This step can be skipped if you are not working on any of the README validation logic. The validation will still run as part of CI. -[Navigate to the official Go Installation page](https://go.dev/doc/install), and install the correct version for your operating system. +Navigate to the [official Go installation page](https://golang.org/doc/install), and install the correct version for your operating system. -Once Go has been installed, verify the installation via: +Once Go has been installed, verify the installation: -```shell +```bash go version ``` -## Namespaces - -All Coder resources are scoped to namespaces placed at the top level of the `/registry` directory. Any modules or templates must be placed inside a namespace to be accepted as a contribution. For example, all modules created by CoderEmployeeBob would be placed under `/registry/coderemployeebob/modules`, with a subdirectory for each individual module the user has published. - -If a namespace is already taken, you will need to create a different, unique namespace, but will still be able to choose any display name. (The display name is shown in the Registry website. More info below.) - -### Namespace (contributor profile) README files +### Understanding Namespaces -More information about contributor profile README files can be found below. +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. -### Images +### Images and Icons -Any images needed for either the main namespace directory or a module/template can be placed in a relative `/images` directory at the top of the namespace directory. (e.g., CoderEmployeeBob can have a `/registry/coderemployeebob/images` directory, that can be referenced by the main README file, as well as a README file in `/registry/coderemployeebob/modules/custom_module/README.md`.) This is to minimize the risk of file name conflicts between different users as they add images to help illustrate parts of their README files. +- Place images in `/registry/[namespace]/images/` to avoid conflicts +- Icons can go in the top-level `/.icons/` directory if used by multiple modules -## Coder modules +--- -### Adding a new module +## Creating a New Module -> [!WARNING] -> These instructions cannot be followed just yet; the script referenced will be made available shortly. Contributors looking to add modules early will need to create all directories manually. +### 1. Create Your Namespace (First Time Only) -Once Bun (and possibly Go) have been installed, clone the Coder Registry repository. From there, you can run this script to make it easier to start contributing a new module or template: +If you're a new contributor, create your namespace: -```shell -./new.sh USER_NAMESPACE/NAME_OF_NEW_MODULE +```bash +mkdir -p registry/[your-username] ``` -You can also create a module file manually by creating the necessary files and directories. - -### The composition of a Coder module - -Each Coder Module must contain the following files: - -- A `main.tf` file that defines the main Terraform-based functionality -- A `main.test.ts` file that is used to validate that the module works as expected -- A `README.md` file containing required information (listed below) - -You are free to include any additional files in the module, as needed by the module. For example, the [Windows RDP module](https://github.com/coder/registry/tree/main/registry/coder/modules/windows-rdp) contains additional files for injecting specific functionality into a Coder Workspace. - -> [!NOTE] -> Some legacy modules do not have test files defined just yet. This will be addressed soon. - -### The `main.tf` file - -This file defines all core Terraform functionality, to be mixed into your Coder workspaces. More information about [Coder's use of Terraform can be found here](https://coder.com/docs/admin/templates/extending-templates/modules), and [general information about the Terraform language can be found in the official documentation](https://developer.hashicorp.com/terraform/docs). - -### The structure of a module README - -Validation criteria for module README files is listed below. - -### Testing a Module - -> [!IMPORTANT] -> It is the responsibility of the module author to implement tests for every new module they wish to contribute. It is expected the author has tested the module locally before opening a PR. Feel free to reference existing test files to get an idea for how to set them up. +Create `registry/[your-username]/README.md`: +```markdown +--- +display_name: "Your Name" +bio: "Brief description" +github: "your-username" +status: "community" +--- -All general-purpose test helpers for validating Terraform can be found in the top-level `/testing` directory. The helpers run `terraform apply` on modules that use variables, testing the script output against containers. +# Your Name +``` -When writing a test file, you can import the test utilities via the `~test` import alias: +### 2. Generate Module Files -```ts -// This works regardless of how deeply-nested your test file is in the file -// structure -import { - runTerraformApply, - runTerraformInit, - testRequiredVariables, -} from "~test"; +```bash +./scripts/new_module.sh [your-username]/[module-name] +cd registry/[your-username]/modules/[module-name] ``` -> [!NOTE] -> The testing suite must be able to run docker containers with the `--network=host` flag. This typically requires running the tests on Linux as this flag does not apply to Docker Desktop for MacOS or Windows. MacOS users can work around this by using something like [colima](https://github.com/abiosoft/colima) or [Orbstack](https://orbstack.dev/) instead of Docker Desktop. +### 3. Build Your Module -#### Running tests +**Edit `main.tf`** - Your Terraform code: +```terraform +terraform { + required_version = ">= 1.0" + required_providers { + coder = { + source = "coder/coder" + version = ">= 0.17" + } + } +} -You can run all tests by running this command from the root of the Registry directory: +variable "agent_id" { + description = "The ID of a Coder agent." + type = string +} -```shell -bun test +resource "coder_script" "install" { + agent_id = var.agent_id + script = file("${path.module}/run.sh") +} ``` -Note that running _all_ tests can take some time, so you likely don't want to be running this command as part of your core development loop. +**Update `README.md`** - Add proper frontmatter: +```markdown +--- +display_name: "Tool Name" +description: "Brief description of what this module does" +icon: "../../../.icons/tool.svg" +maintainer_github: "your-username" +verified: false +tags: ["development", "tool"] +--- -To run specific tests, you can use the `-t` flag, which accepts a filepath regex: +# Tool Name -```shell -bun test -t '' -``` +Brief description and usage example. -To ensure that the module runs predictably in local development, you can update the Terraform source as follows: +## Usage ```tf -module "example" { - # You may need to remove the 'version' field, it is incompatible with some sources. - source = "git::https://github.com//.git//?ref=" +module "tool" { + source = "registry.coder.com/[username]/[module]/coder" + version = "1.0.0" + agent_id = coder_agent.main.id } ``` +``` -## Updating README files +**Write tests in `main.test.ts`**: +```typescript +import { runTerraformApply, runTerraformInit, testRequiredVariables } from "~test"; + +describe("module-name", () => { + it("should have required variables", async () => { + await testRequiredVariables(import.meta.dir); + }); + + it("should apply successfully", async () => { + await runTerraformInit(import.meta.dir); + await runTerraformApply(import.meta.dir, { + agent_id: "test-agent-id", + }); + }); +}); +``` -This repo uses Go to validate each README file. If you are working with the README files at all (i.e., creating them, modifying them), it is strongly recommended that you install Go (installation instructions mentioned above), so that the files can be validated locally. +### 4. Test and Submit -### Validating all README files +```bash +# Test your module +bun test -To validate all README files throughout the entire repo, you can run the following: +# Format code +bun run fmt -```shell -go build ./cmd/readmevalidation && ./readmevalidation +# Commit and create PR +git add . +git commit -m "Add [module-name] module" +git push origin your-branch ``` -The resulting binary is already part of the `.gitignore` file, but you can remove it with: +> **Important**: It is your responsibility to implement tests for every new module. Test your module locally before opening a PR. The testing suite requires Docker containers with the `--network=host` flag, which typically requires running tests on Linux (this flag doesn't work with Docker Desktop on macOS/Windows). macOS users can use [Colima](https://github.com/abiosoft/colima) or [OrbStack](https://orbstack.dev/) instead of Docker Desktop. + +--- -```shell -rm ./readmevalidation +## Contributing to Existing Modules + +### 1. Find the Module + +```bash +find registry -name "*[module-name]*" -type d ``` -### README validation criteria +### 2. Make Your Changes -The following criteria exists for two reasons: +**For bug fixes:** +- Reproduce the issue +- Fix the code in `main.tf` +- Add/update tests +- Update documentation if needed -1. Content accessibility -2. Having content be designed in a way that's easy for the Registry site build step to use +**For new features:** +- Add new variables with sensible defaults +- Implement the feature +- Add tests for new functionality +- Update README with new variables -#### General README requirements +**For documentation:** +- Fix typos and unclear explanations +- Add missing variable documentation +- Improve usage examples -- There must be a frontmatter section. -- There must be exactly one h1 header, and it must be at the very top, directly below the frontmatter. -- The README body (if it exists) must start with an h1 header. No other content (including GitHub-Flavored Markdown alerts) is allowed to be placed above it. -- When increasing the level of a header, the header's level must be incremented by one each time. -- Any `.hcl` code snippets must be labeled as `.tf` snippets instead +### 3. Test Your Changes - ```txt - \`\`\`tf - Content - \`\`\` - ``` +```bash +cd registry/[namespace]/modules/[module-name] -#### Namespace (contributor profile) criteria +# Test the specific module +bun test -In addition to the general criteria, all README files must have the following: +# Test all modules (from repo root) +bun test +``` -- Frontmatter metadata with support for the following fields: +### 4. Maintain Backward Compatibility - - `display_name` (required string) – The name to use when displaying your user profile in the Coder Registry site. - - `bio` (optional string) – A short description of who you are. - - `github` (optional string) – Your GitHub handle. - - `avatar_url` (optional string) – A relative/absolute URL pointing to your avatar for the Registry site. It is strongly recommended that you commit avatar images to this repo and reference them via a relative URL. - - `linkedin` (optional string) – A URL pointing to your LinkedIn page. - - `support_email` (optional string) – An email for users to reach you at if they need help with a published module/template. - - `status` (string union) – If defined, this must be one of `"community"`, `"partner"`, or `"official"`. `"community"` should be used for the majority of external contributions. `"partner"` is for companies who have a formal business partnership with Coder. `"official"` should be used only by Coder employees. +- New variables should have default values +- Don't break existing functionality +- Test that minimal configurations still work -- The README body (the content that goes directly below the frontmatter) is allowed to be empty, but if it isn't, it must follow all the rules above. +--- -You are free to customize the body of a contributor profile however you like, adding any number of images or information. Its content will never be rendered in the Registry website. +## Submitting Changes -Additional information can be placed in the README file below the content listed above, using any number of headers. +### Create a Pull Request -Additional image/video assets can be placed in the same user namespace directory where that user's main content lives. +1. **Fork and branch:** + ```bash + git checkout -b fix/module-name-issue + ``` -#### Module criteria +2. **Commit with clear messages:** + ```bash + git commit -m "Fix version parsing in module-name" + ``` -In addition to the general criteria, all README files must have the following: +3. **Open PR with:** + - Clear title describing the change + - What you changed and why + - Any breaking changes -- Frontmatter that describes metadata for the module: - - `display_name` (required string) – This is the name displayed on the Coder Registry website - - `description` (required string) – A short description of the module, which is displayed on the Registry website - - `icon` (required string) – A relative/absolute URL pointing to the icon to display for the module in the Coder Registry website. - - `verified` (optional boolean) – Indicates whether the module has been officially verified by Coder. Please do not set this without approval from a Coder employee. - - `tags` (required string array) – A list of metadata tags to describe the module. Used in the Registry site for search and navigation functionality. - - `maintainer_github` (deprecated string) – The name of the creator of the module. This field exists for backwards compatibility with previous versions of the Registry, but going forward, the value will be inferred from the namespace directory. - - `partner_github` (deprecated string) - The name of any additional creators for a module. This field exists for backwards compatibility with previous versions of the Registry, but should not ever be used going forward. -- The following content directly under the h1 header (without another header between them): +### PR Template +```markdown +## Description +Brief description of changes. - - A description of what the module does - - A Terraform snippet for letting other users import the functionality +## Type of Change +- [ ] New module +- [ ] Bug fix +- [ ] Feature enhancement +- [ ] Documentation - ```tf - module "cursor" { - count = data.coder_workspace.me.start_count - source = "registry.coder.com/coder/cursor/coder" - version = "1.0.19" - agent_id = coder_agent.example.id - } - ``` +## Testing +- [ ] Tests pass (`bun test`) +- [ ] Code formatted (`bun run fmt`) +``` -Additional information can be placed in the README file below the content listed above, using any number of headers. +--- + +## Requirements + +### Every Module Must Have +- `main.tf` - Terraform code +- `main.test.ts` - Working tests +- `README.md` - Documentation with frontmatter + +### README Frontmatter +```yaml +--- +display_name: "Module Name" # Required - Name shown on Registry website +description: "What it does" # Required - Short description for Registry +icon: "path/to/icon.svg" # Required - Path to icon file +maintainer_github: "your-username" # Required - Your GitHub username +verified: false # Optional - Set by Coder maintainers only +tags: ["tag1", "tag2"] # Required - Array of descriptive tags +partner_github: "partner-name" # Optional - For official partnerships only +--- +``` -Additional image/video assets can be placed in one of two places: +### README Requirements -1. In the same user namespace directory where that user's main content lives -2. If the image is an icon, it can be placed in the top-level `.icons` directory (this is done because a lot of modules will be based off the same products) +All README files must follow these rules: +- Must have frontmatter section with proper YAML +- Exactly one h1 header directly below frontmatter +- When increasing header levels, increment by one each time +- Use `tf` instead of `hcl` for code blocks -## Releases +### Best Practices +- Use descriptive variable names and descriptions +- Include helpful comments +- Test all functionality +- Follow existing code patterns in the module -The release process involves the following steps: +--- -### 1. Create and merge a new PR +## README Validation -- Create a PR with your module changes -- Get your PR reviewed, approved, and merged into the `main` branch +If you installed Go, you can validate README files locally: -### 2. Prepare Release (Maintainer Task) +```bash +go build ./cmd/readmevalidation && ./readmevalidation +``` -After merging to `main`, a maintainer will: +--- -- Check out the merge commit: +## Release Process - ```shell - git checkout MERGE_COMMIT_ID - ``` +After your PR is merged, maintainers will handle the release: -- Create annotated tags for each module that was changed: +1. **Create release tags** for changed modules: + ```bash + git tag -a "release/$namespace/$module/v$version" -m "Release $namespace/$module v$version" + git push origin release/$namespace/$module/v$version + ``` - ```shell - git tag -a "release/$namespace/$module/v$version" -m "Release $namespace/$module v$version" - ``` +2. **Version numbers** follow semantic versioning: + - **Patch** (1.2.3 → 1.2.4): Bug fixes + - **Minor** (1.2.3 → 1.3.0): New features, adding inputs + - **Major** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing types) -- Push the tags to origin: +3. **Publishing**: Changes are automatically published to [registry.coder.com](https://registry.coder.com) after tags are pushed. - ```shell - git push origin release/$namespace/$module/v$version - ``` +--- -For example, to release version 1.0.14 of the coder/aider module: +## Reporting Issues -```shell -git tag -a "release/coder/aider/v1.0.14" -m "Release coder/aider v1.0.14" -git push origin release/coder/aider/v1.0.14 -``` +When reporting bugs, include: +- Module name and version +- Expected vs actual behavior +- Minimal reproduction case +- Error messages +- Environment details (OS, Terraform version) -### Version Numbers +--- -Version numbers should follow semantic versioning: +## Getting Help -- **Patch version** (1.2.3 → 1.2.4): Bug fixes -- **Minor version** (1.2.3 → 1.3.0): New features, adding inputs, deprecating inputs -- **Major version** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing input types) +- **Examples**: Check `/registry/coder/modules/` for well-structured modules +- **Issues**: Open an issue for technical problems +- **Community**: Reach out to the Coder community for questions -### 3. Publishing to Coder Registry +## Common Pitfalls -After tags are pushed, the changes will be published to [registry.coder.com](https://registry.coder.com). +1. **Missing frontmatter** in README +2. **No tests** or broken tests +3. **Hardcoded values** instead of variables +4. **Breaking changes** without defaults +5. **Not running** `bun run fmt` before submitting -> [!NOTE] -> Some data in registry.coder.com is fetched on demand from this repository's `main` branch. This data should update almost immediately after a release, while other changes will take some time to propagate. +Happy contributing! 🚀 From ad7033c8f3a3592059bf54769b1e84d5ff5afb3a Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Wed, 28 May 2025 01:54:21 +0000 Subject: [PATCH 02/26] docs(MAINTAINER): add maintainer guide for repository management and processes --- MAINTAINER.md | 292 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 MAINTAINER.md diff --git a/MAINTAINER.md b/MAINTAINER.md new file mode 100644 index 000000000..edc6a8005 --- /dev/null +++ b/MAINTAINER.md @@ -0,0 +1,292 @@ +# Maintainer Guide + +This guide is for maintainers of the Coder Registry repository. It covers processes and tools that are specific to maintaining the repository, validating contributions, and managing releases. + +## Prerequisites + +### Required Tools + +- **Go** - For README validation +- **Bun** - For running tests +- **Git** - For repository management + +### Installing Go + +[Navigate to the official Go Installation page](https://go.dev/doc/install), and install the correct version for your operating system. + +Once Go has been installed, verify the installation via: + +```shell +go version +``` + +## README Validation + +The repository uses Go to validate all README files to ensure they meet the requirements for the Registry website. + +### Running README Validation + +To validate all README files throughout the entire repo: + +```shell +go build ./cmd/readmevalidation && ./readmevalidation +``` + +The resulting binary is already part of the `.gitignore` file, but you can remove it with: + +```shell +rm ./readmevalidation +``` + +### README Validation Criteria + +The validation exists for two reasons: + +1. Content accessibility +2. Having content designed in a way that's easy for the Registry site build step to use + +#### General README Requirements + +- There must be a frontmatter section +- There must be exactly one h1 header, and it must be at the very top, directly below the frontmatter +- The README body (if it exists) must start with an h1 header. No other content (including GitHub-Flavored Markdown alerts) is allowed to be placed above it +- When increasing the level of a header, the header's level must be incremented by one each time +- Any `.hcl` code snippets must be labeled as `.tf` snippets instead + + ```txt + \`\`\`tf + Content + \`\`\` + ``` + +#### Namespace (Contributor Profile) Criteria + +In addition to the general criteria, all namespace README files must have: + +- Frontmatter metadata with support for the following fields: + - `display_name` (required string) – The name to use when displaying the user profile in the Coder Registry site + - `bio` (optional string) – A short description of who they are + - `github` (optional string) – Their GitHub handle + - `avatar_url` (optional string) – A relative/absolute URL pointing to their avatar for the Registry site + - `linkedin` (optional string) – A URL pointing to their LinkedIn page + - `support_email` (optional string) – An email for users to reach them at if they need help with a published module + - `status` (string union) – If defined, this must be one of `"community"`, `"partner"`, or `"official"`. `"community"` should be used for the majority of external contributions. `"partner"` is for companies who have a formal business partnership with Coder. `"official"` should be used only by Coder employees + +- The README body (the content that goes directly below the frontmatter) is allowed to be empty, but if it isn't, it must follow all the rules above + +#### Module Criteria + +In addition to the general criteria, all module README files must have: + +- Frontmatter that describes metadata for the module: + - `display_name` (required string) – This is the name displayed on the Coder Registry website + - `description` (required string) – A short description of the module, which is displayed on the Registry website + - `icon` (required string) – A relative/absolute URL pointing to the icon to display for the module in the Coder Registry website + - `verified` (optional boolean) – Indicates whether the module has been officially verified by Coder. Please do not set this without approval from a Coder employee + - `tags` (required string array) – A list of metadata tags to describe the module. Used in the Registry site for search and navigation functionality + - `maintainer_github` (deprecated string) – The name of the creator of the module. This field exists for backwards compatibility with previous versions of the Registry, but going forward, the value will be inferred from the namespace directory + - `partner_github` (deprecated string) - The name of any additional creators for a module. This field exists for backwards compatibility with previous versions of the Registry, but should not ever be used going forward + +- The following content directly under the h1 header (without another header between them): + - A description of what the module does + - A Terraform snippet for letting other users import the functionality + + ```tf + module "cursor" { + count = data.coder_workspace.me.start_count + source = "registry.coder.com/coder/cursor/coder" + version = "1.0.19" + agent_id = coder_agent.example.id + } + ``` + +## Release Process + +The release process involves the following steps: + +### 1. Review and Merge PRs + +- Review contributor PRs for code quality, tests, and documentation +- Ensure all automated tests pass +- Verify README validation passes +- Merge approved PRs into the `main` branch + +### 2. Prepare Release + +After merging to `main`, prepare the release: + +- Check out the merge commit: + + ```shell + git checkout MERGE_COMMIT_ID + ``` + +- Create annotated tags for each module that was changed: + + ```shell + git tag -a "release/$namespace/$module/v$version" -m "Release $namespace/$module v$version" + ``` + +- Push the tags to origin: + + ```shell + git push origin release/$namespace/$module/v$version + ``` + +For example, to release version 1.0.14 of the coder/aider module: + +```shell +git tag -a "release/coder/aider/v1.0.14" -m "Release coder/aider v1.0.14" +git push origin release/coder/aider/v1.0.14 +``` + +### Version Numbers + +Version numbers should follow semantic versioning: + +- **Patch version** (1.2.3 → 1.2.4): Bug fixes +- **Minor version** (1.2.3 → 1.3.0): New features, adding inputs, deprecating inputs +- **Major version** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing input types) + +### 3. Publishing to Coder Registry + +After tags are pushed, the changes will be published to [registry.coder.com](https://registry.coder.com). + +> [!NOTE] +> Some data in registry.coder.com is fetched on demand from this repository's `main` branch. This data should update almost immediately after a release, while other changes will take some time to propagate. + +## Testing Infrastructure + +### Running All Tests + +From the repository root: + +```shell +bun test +``` + +### Running Specific Tests + +To run tests for specific modules or patterns: + +```shell +bun test -t '' +``` + +### Test Requirements + +- All modules must have a `main.test.ts` file +- Tests must use the test utilities from `~test` import +- Tests must validate required variables and successful Terraform apply +- The testing suite requires Docker with `--network=host` capabilities + +## Repository Structure Management + +### Namespaces + +- All modules must be placed within a namespace under `/registry/[namespace]/modules/` +- Each namespace should have a README.md file with contributor profile information +- Namespace names must be unique and lowercase + +### Images and Assets + +Images can be placed in two locations: + +1. In the namespace directory: `/registry/[namespace]/images/` +2. For icons used by multiple modules: `/.icons/` + +### Module Structure + +Each module must contain: + +- `main.tf` - Core Terraform functionality +- `main.test.ts` - Test file for validation +- `README.md` - Documentation with required frontmatter + +## Validation Checklist for PRs + +When reviewing PRs, ensure: + +- [ ] Module follows proper directory structure +- [ ] All required files are present (`main.tf`, `main.test.ts`, `README.md`) +- [ ] README has proper frontmatter with all required fields +- [ ] Tests are implemented and pass +- [ ] Code is properly formatted (`bun run fmt`) +- [ ] README validation passes +- [ ] Module follows Terraform best practices +- [ ] No hardcoded values that should be variables +- [ ] Proper variable descriptions and types + +## Common Issues and Solutions + +### README Validation Failures + +- Check frontmatter syntax (YAML format) +- Ensure h1 header is directly below frontmatter +- Verify all required frontmatter fields are present +- Check that code blocks use `tf` instead of `hcl` + +### Test Failures + +- Ensure Docker is available with `--network=host` support +- Check that all required variables are defined in tests +- Verify Terraform syntax is valid +- Ensure test imports use `~test` alias correctly + +### Module Structure Issues + +- Use the `./scripts/new_module.sh` script for consistent structure +- Ensure namespace directory exists +- Check that all file paths are correct + +## Maintenance Tasks + +### Regular Maintenance + +- Monitor for security vulnerabilities in dependencies +- Update test infrastructure as needed +- Review and update documentation +- Monitor Registry website for issues + +### Dependency Updates + +- Keep Bun dependencies up to date +- Monitor Terraform provider updates +- Update test utilities as needed + +### Documentation Updates + +- Keep README validation criteria current +- Update examples as the platform evolves +- Maintain contributor guidelines + +## Emergency Procedures + +### Reverting a Release + +If a release needs to be reverted: + +1. Delete the problematic tag: + ```shell + git tag -d release/$namespace/$module/v$version + git push origin :refs/tags/release/$namespace/$module/v$version + ``` + +2. Create a new patch release with the fix + +### Handling Security Issues + +1. Immediately remove or disable problematic modules +2. Notify affected users through appropriate channels +3. Work with contributors to address security concerns +4. Document the issue and resolution + +## Contact and Escalation + +For maintainer-specific questions or issues: + +- Internal Coder team channels +- Repository issues for public discussion +- Security email for sensitive issues + +Remember: As a maintainer, you're responsible for maintaining the quality and security of the Registry. When in doubt, err on the side of caution and seek additional review. \ No newline at end of file From 17ddbe89cfe83ebe634b21b1903878709c5e652a Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Wed, 28 May 2025 01:57:10 +0000 Subject: [PATCH 03/26] docs(CONTRIBUTING): prettier formatting --- CONTRIBUTING.md | 43 +++++++++++++++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d306bde1a..cb0a7b8e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,11 +15,13 @@ The Coder Registry is a collection of Terraform modules that extend Coder worksp ## Setup ### Prerequisites + - Git and GitHub account - Basic Terraform knowledge (for module development) - Docker (for running tests) ### Install Dependencies + ```bash # Install Bun (test runner) curl -fsSL https://bun.sh/install | bash @@ -65,6 +67,7 @@ mkdir -p registry/[your-username] ``` Create `registry/[your-username]/README.md`: + ```markdown --- display_name: "Your Name" @@ -86,6 +89,7 @@ cd registry/[your-username]/modules/[module-name] ### 3. Build Your Module **Edit `main.tf`** - Your Terraform code: + ```terraform terraform { required_version = ">= 1.0" @@ -109,7 +113,8 @@ resource "coder_script" "install" { ``` **Update `README.md`** - Add proper frontmatter: -```markdown + +````markdown --- display_name: "Tool Name" description: "Brief description of what this module does" @@ -132,7 +137,9 @@ module "tool" { agent_id = coder_agent.main.id } ``` -``` +```` + +```` **Write tests in `main.test.ts`**: ```typescript @@ -150,7 +157,7 @@ describe("module-name", () => { }); }); }); -``` +```` ### 4. Test and Submit @@ -182,18 +189,21 @@ find registry -name "*[module-name]*" -type d ### 2. Make Your Changes **For bug fixes:** + - Reproduce the issue - Fix the code in `main.tf` - Add/update tests - Update documentation if needed **For new features:** + - Add new variables with sensible defaults - Implement the feature - Add tests for new functionality - Update README with new variables **For documentation:** + - Fix typos and unclear explanations - Add missing variable documentation - Improve usage examples @@ -223,11 +233,13 @@ bun test ### Create a Pull Request 1. **Fork and branch:** + ```bash git checkout -b fix/module-name-issue ``` 2. **Commit with clear messages:** + ```bash git commit -m "Fix version parsing in module-name" ``` @@ -238,17 +250,21 @@ bun test - Any breaking changes ### PR Template + ```markdown ## Description + Brief description of changes. ## Type of Change + - [ ] New module -- [ ] Bug fix +- [ ] Bug fix - [ ] Feature enhancement - [ ] Documentation ## Testing + - [ ] Tests pass (`bun test`) - [ ] Code formatted (`bun run fmt`) ``` @@ -258,32 +274,36 @@ Brief description of changes. ## Requirements ### Every Module Must Have + - `main.tf` - Terraform code - `main.test.ts` - Working tests - `README.md` - Documentation with frontmatter ### README Frontmatter + ```yaml --- -display_name: "Module Name" # Required - Name shown on Registry website -description: "What it does" # Required - Short description for Registry -icon: "path/to/icon.svg" # Required - Path to icon file +display_name: "Module Name" # Required - Name shown on Registry website +description: "What it does" # Required - Short description for Registry +icon: "path/to/icon.svg" # Required - Path to icon file maintainer_github: "your-username" # Required - Your GitHub username -verified: false # Optional - Set by Coder maintainers only -tags: ["tag1", "tag2"] # Required - Array of descriptive tags -partner_github: "partner-name" # Optional - For official partnerships only +verified: false # Optional - Set by Coder maintainers only +tags: ["tag1", "tag2"] # Required - Array of descriptive tags +partner_github: "partner-name" # Optional - For official partnerships only --- ``` ### README Requirements All README files must follow these rules: + - Must have frontmatter section with proper YAML - Exactly one h1 header directly below frontmatter - When increasing header levels, increment by one each time - Use `tf` instead of `hcl` for code blocks ### Best Practices + - Use descriptive variable names and descriptions - Include helpful comments - Test all functionality @@ -306,12 +326,14 @@ go build ./cmd/readmevalidation && ./readmevalidation After your PR is merged, maintainers will handle the release: 1. **Create release tags** for changed modules: + ```bash git tag -a "release/$namespace/$module/v$version" -m "Release $namespace/$module v$version" git push origin release/$namespace/$module/v$version ``` 2. **Version numbers** follow semantic versioning: + - **Patch** (1.2.3 → 1.2.4): Bug fixes - **Minor** (1.2.3 → 1.3.0): New features, adding inputs - **Major** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing types) @@ -323,6 +345,7 @@ After your PR is merged, maintainers will handle the release: ## Reporting Issues When reporting bugs, include: + - Module name and version - Expected vs actual behavior - Minimal reproduction case From 12060cbd0d92d0d30222eb1b68bd963fb809f34c Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Wed, 28 May 2025 01:57:36 +0000 Subject: [PATCH 04/26] docs(MAINTAINER): Prettier Formatting --- MAINTAINER.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/MAINTAINER.md b/MAINTAINER.md index edc6a8005..c4601782f 100644 --- a/MAINTAINER.md +++ b/MAINTAINER.md @@ -64,6 +64,7 @@ The validation exists for two reasons: In addition to the general criteria, all namespace README files must have: - Frontmatter metadata with support for the following fields: + - `display_name` (required string) – The name to use when displaying the user profile in the Coder Registry site - `bio` (optional string) – A short description of who they are - `github` (optional string) – Their GitHub handle @@ -79,6 +80,7 @@ In addition to the general criteria, all namespace README files must have: In addition to the general criteria, all module README files must have: - Frontmatter that describes metadata for the module: + - `display_name` (required string) – This is the name displayed on the Coder Registry website - `description` (required string) – A short description of the module, which is displayed on the Registry website - `icon` (required string) – A relative/absolute URL pointing to the icon to display for the module in the Coder Registry website @@ -88,6 +90,7 @@ In addition to the general criteria, all module README files must have: - `partner_github` (deprecated string) - The name of any additional creators for a module. This field exists for backwards compatibility with previous versions of the Registry, but should not ever be used going forward - The following content directly under the h1 header (without another header between them): + - A description of what the module does - A Terraform snippet for letting other users import the functionality @@ -267,6 +270,7 @@ When reviewing PRs, ensure: If a release needs to be reverted: 1. Delete the problematic tag: + ```shell git tag -d release/$namespace/$module/v$version git push origin :refs/tags/release/$namespace/$module/v$version @@ -289,4 +293,4 @@ For maintainer-specific questions or issues: - Repository issues for public discussion - Security email for sensitive issues -Remember: As a maintainer, you're responsible for maintaining the quality and security of the Registry. When in doubt, err on the side of caution and seek additional review. \ No newline at end of file +Remember: As a maintainer, you're responsible for maintaining the quality and security of the Registry. When in doubt, err on the side of caution and seek additional review. From a02e173b2f074a5193b5c6c9d9eb67107aa0f2d0 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Wed, 28 May 2025 02:03:42 +0000 Subject: [PATCH 05/26] docs(CONTRIBUTING): Update installation instructions for Bun and Terraform --- CONTRIBUTING.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb0a7b8e6..09028d493 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,16 +18,26 @@ The Coder Registry is a collection of Terraform modules that extend Coder worksp - Git and GitHub account - Basic Terraform knowledge (for module development) +- Terraform installed ([installation guide](https://developer.hashicorp.com/terraform/install)) - Docker (for running tests) ### Install Dependencies +Install Bun (test runner): + ```bash -# Install Bun (test runner) curl -fsSL https://bun.sh/install | bash +``` + +Restart your terminal or source your profile: + +```bash source ~/.bashrc +``` -# Install project dependencies +Install project dependencies: + +```bash bun install ``` From da39b2c201c54afa755a4fac247290285835792c Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Wed, 28 May 2025 02:10:08 +0000 Subject: [PATCH 06/26] docs(MAINTAINER): Revise maintainer guide for clarity and conciseness --- MAINTAINER.md | 315 +++++++++----------------------------------------- 1 file changed, 54 insertions(+), 261 deletions(-) diff --git a/MAINTAINER.md b/MAINTAINER.md index c4601782f..1a861cc28 100644 --- a/MAINTAINER.md +++ b/MAINTAINER.md @@ -1,296 +1,89 @@ # Maintainer Guide -This guide is for maintainers of the Coder Registry repository. It covers processes and tools that are specific to maintaining the repository, validating contributions, and managing releases. +Quick reference for maintaining the Coder Registry repository. -## Prerequisites +## Setup -### Required Tools +Install Go for README validation: -- **Go** - For README validation -- **Bun** - For running tests -- **Git** - For repository management +```bash +# macOS +brew install go -### Installing Go - -[Navigate to the official Go Installation page](https://go.dev/doc/install), and install the correct version for your operating system. - -Once Go has been installed, verify the installation via: - -```shell -go version +# Linux +sudo apt install golang-go ``` -## README Validation +## Daily Tasks -The repository uses Go to validate all README files to ensure they meet the requirements for the Registry website. +### Review PRs -### Running README Validation +Check that PRs have: -To validate all README files throughout the entire repo: - -```shell -go build ./cmd/readmevalidation && ./readmevalidation -``` +- [ ] All required files (`main.tf`, `main.test.ts`, `README.md`) +- [ ] Proper frontmatter in README +- [ ] Working tests (`bun test`) +- [ ] Formatted code (`bun run fmt`) -The resulting binary is already part of the `.gitignore` file, but you can remove it with: +### Validate READMEs -```shell -rm ./readmevalidation +```bash +go build ./cmd/readmevalidation && ./readmevalidation ``` -### README Validation Criteria - -The validation exists for two reasons: - -1. Content accessibility -2. Having content designed in a way that's easy for the Registry site build step to use - -#### General README Requirements - -- There must be a frontmatter section -- There must be exactly one h1 header, and it must be at the very top, directly below the frontmatter -- The README body (if it exists) must start with an h1 header. No other content (including GitHub-Flavored Markdown alerts) is allowed to be placed above it -- When increasing the level of a header, the header's level must be incremented by one each time -- Any `.hcl` code snippets must be labeled as `.tf` snippets instead - - ```txt - \`\`\`tf - Content - \`\`\` - ``` - -#### Namespace (Contributor Profile) Criteria - -In addition to the general criteria, all namespace README files must have: - -- Frontmatter metadata with support for the following fields: - - - `display_name` (required string) – The name to use when displaying the user profile in the Coder Registry site - - `bio` (optional string) – A short description of who they are - - `github` (optional string) – Their GitHub handle - - `avatar_url` (optional string) – A relative/absolute URL pointing to their avatar for the Registry site - - `linkedin` (optional string) – A URL pointing to their LinkedIn page - - `support_email` (optional string) – An email for users to reach them at if they need help with a published module - - `status` (string union) – If defined, this must be one of `"community"`, `"partner"`, or `"official"`. `"community"` should be used for the majority of external contributions. `"partner"` is for companies who have a formal business partnership with Coder. `"official"` should be used only by Coder employees - -- The README body (the content that goes directly below the frontmatter) is allowed to be empty, but if it isn't, it must follow all the rules above - -#### Module Criteria - -In addition to the general criteria, all module README files must have: +## Releases -- Frontmatter that describes metadata for the module: +### Create Release Tags - - `display_name` (required string) – This is the name displayed on the Coder Registry website - - `description` (required string) – A short description of the module, which is displayed on the Registry website - - `icon` (required string) – A relative/absolute URL pointing to the icon to display for the module in the Coder Registry website - - `verified` (optional boolean) – Indicates whether the module has been officially verified by Coder. Please do not set this without approval from a Coder employee - - `tags` (required string array) – A list of metadata tags to describe the module. Used in the Registry site for search and navigation functionality - - `maintainer_github` (deprecated string) – The name of the creator of the module. This field exists for backwards compatibility with previous versions of the Registry, but going forward, the value will be inferred from the namespace directory - - `partner_github` (deprecated string) - The name of any additional creators for a module. This field exists for backwards compatibility with previous versions of the Registry, but should not ever be used going forward +After merging a PR: -- The following content directly under the h1 header (without another header between them): - - - A description of what the module does - - A Terraform snippet for letting other users import the functionality - - ```tf - module "cursor" { - count = data.coder_workspace.me.start_count - source = "registry.coder.com/coder/cursor/coder" - version = "1.0.19" - agent_id = coder_agent.example.id - } - ``` - -## Release Process - -The release process involves the following steps: - -### 1. Review and Merge PRs - -- Review contributor PRs for code quality, tests, and documentation -- Ensure all automated tests pass -- Verify README validation passes -- Merge approved PRs into the `main` branch - -### 2. Prepare Release - -After merging to `main`, prepare the release: - -- Check out the merge commit: - - ```shell - git checkout MERGE_COMMIT_ID - ``` - -- Create annotated tags for each module that was changed: - - ```shell - git tag -a "release/$namespace/$module/v$version" -m "Release $namespace/$module v$version" - ``` - -- Push the tags to origin: - - ```shell - git push origin release/$namespace/$module/v$version - ``` - -For example, to release version 1.0.14 of the coder/aider module: - -```shell -git tag -a "release/coder/aider/v1.0.14" -m "Release coder/aider v1.0.14" -git push origin release/coder/aider/v1.0.14 +```bash +git checkout MERGE_COMMIT_ID +git tag -a "release/$namespace/$module/v$version" -m "Release $namespace/$module v$version" +git push origin release/$namespace/$module/v$version ``` ### Version Numbers -Version numbers should follow semantic versioning: - -- **Patch version** (1.2.3 → 1.2.4): Bug fixes -- **Minor version** (1.2.3 → 1.3.0): New features, adding inputs, deprecating inputs -- **Major version** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing input types) - -### 3. Publishing to Coder Registry - -After tags are pushed, the changes will be published to [registry.coder.com](https://registry.coder.com). +- **Patch** (1.2.3 → 1.2.4): Bug fixes +- **Minor** (1.2.3 → 1.3.0): New features, adding inputs +- **Major** (1.2.3 → 2.0.0): Breaking changes -> [!NOTE] -> Some data in registry.coder.com is fetched on demand from this repository's `main` branch. This data should update almost immediately after a release, while other changes will take some time to propagate. +## README Requirements -## Testing Infrastructure +### Module Frontmatter (Required) -### Running All Tests - -From the repository root: - -```shell -bun test +```yaml +display_name: "Tool Name" +description: "What it does" +icon: "path/to/icon.svg" +maintainer_github: "username" +verified: false # true for verified modules +tags: ["tag1", "tag2"] ``` -### Running Specific Tests - -To run tests for specific modules or patterns: +### Namespace Frontmatter (Required) -```shell -bun test -t '' +```yaml +display_name: "Your Name" +bio: "Brief description" +github: "username" +status: "community" # or "partner", "official" ``` -### Test Requirements - -- All modules must have a `main.test.ts` file -- Tests must use the test utilities from `~test` import -- Tests must validate required variables and successful Terraform apply -- The testing suite requires Docker with `--network=host` capabilities - -## Repository Structure Management - -### Namespaces - -- All modules must be placed within a namespace under `/registry/[namespace]/modules/` -- Each namespace should have a README.md file with contributor profile information -- Namespace names must be unique and lowercase - -### Images and Assets - -Images can be placed in two locations: - -1. In the namespace directory: `/registry/[namespace]/images/` -2. For icons used by multiple modules: `/.icons/` - -### Module Structure - -Each module must contain: - -- `main.tf` - Core Terraform functionality -- `main.test.ts` - Test file for validation -- `README.md` - Documentation with required frontmatter - -## Validation Checklist for PRs - -When reviewing PRs, ensure: - -- [ ] Module follows proper directory structure -- [ ] All required files are present (`main.tf`, `main.test.ts`, `README.md`) -- [ ] README has proper frontmatter with all required fields -- [ ] Tests are implemented and pass -- [ ] Code is properly formatted (`bun run fmt`) -- [ ] README validation passes -- [ ] Module follows Terraform best practices -- [ ] No hardcoded values that should be variables -- [ ] Proper variable descriptions and types - -## Common Issues and Solutions - -### README Validation Failures - -- Check frontmatter syntax (YAML format) -- Ensure h1 header is directly below frontmatter -- Verify all required frontmatter fields are present -- Check that code blocks use `tf` instead of `hcl` +## Common Issues -### Test Failures +- **README validation fails**: Check YAML syntax, ensure h1 header after frontmatter +- **Tests fail**: Ensure Docker with `--network=host`, check Terraform syntax +- **Wrong file structure**: Use `./scripts/new_module.sh` for new modules -- Ensure Docker is available with `--network=host` support -- Check that all required variables are defined in tests -- Verify Terraform syntax is valid -- Ensure test imports use `~test` alias correctly +## Emergency -### Module Structure Issues +### Revert Release -- Use the `./scripts/new_module.sh` script for consistent structure -- Ensure namespace directory exists -- Check that all file paths are correct - -## Maintenance Tasks - -### Regular Maintenance - -- Monitor for security vulnerabilities in dependencies -- Update test infrastructure as needed -- Review and update documentation -- Monitor Registry website for issues - -### Dependency Updates - -- Keep Bun dependencies up to date -- Monitor Terraform provider updates -- Update test utilities as needed - -### Documentation Updates - -- Keep README validation criteria current -- Update examples as the platform evolves -- Maintain contributor guidelines - -## Emergency Procedures - -### Reverting a Release - -If a release needs to be reverted: - -1. Delete the problematic tag: - - ```shell - git tag -d release/$namespace/$module/v$version - git push origin :refs/tags/release/$namespace/$module/v$version - ``` - -2. Create a new patch release with the fix - -### Handling Security Issues - -1. Immediately remove or disable problematic modules -2. Notify affected users through appropriate channels -3. Work with contributors to address security concerns -4. Document the issue and resolution - -## Contact and Escalation - -For maintainer-specific questions or issues: - -- Internal Coder team channels -- Repository issues for public discussion -- Security email for sensitive issues +```bash +git tag -d release/$namespace/$module/v$version +git push origin :refs/tags/release/$namespace/$module/v$version +``` -Remember: As a maintainer, you're responsible for maintaining the quality and security of the Registry. When in doubt, err on the side of caution and seek additional review. +That's it. Keep it simple. From 1e826a3f5e877bca6469d6ca5738dbc2d84e3a40 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Thu, 29 May 2025 02:12:27 +0000 Subject: [PATCH 07/26] docs(CONTRIBUTING): Enhance contributing guidelines with avatar and image instructions --- CONTRIBUTING.md | 73 +++++++++++++++++++++++-------------------------- 1 file changed, 34 insertions(+), 39 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 09028d493..43cfac0e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,8 +61,9 @@ All modules are organized under `/registry/[namespace]/modules/`. Each contribut ### Images and Icons -- Place images in `/registry/[namespace]/images/` to avoid conflicts -- Icons can go in the top-level `/.icons/` directory if used by multiple modules +- **Namespace avatars**: Place your avatar in `/registry/[namespace]/images/` +- **Module images**: Place other images in `/registry/[namespace]/images/` to avoid conflicts +- **Module icons**: Can go in the top-level `/.icons/` directory if used by multiple modules --- @@ -74,14 +75,26 @@ If you're a new contributor, create your namespace: ```bash mkdir -p registry/[your-username] +mkdir -p registry/[your-username]/images ``` +#### Add Your Avatar + +Every namespace should have an avatar. Add your avatar image: + +1. Add a square image (recommended: 400x400px minimum) to `registry/[your-username]/images/` +2. Supported formats: `.png`, `.jpg`, `.jpeg`, `.svg` +3. Name it something clear like `avatar.png` or `profile.jpg` + +#### Create Your Namespace README + Create `registry/[your-username]/README.md`: ```markdown --- display_name: "Your Name" -bio: "Brief description" +bio: "Brief description of what you do" +avatar_url: "./images/avatar.png" github: "your-username" status: "community" --- @@ -89,6 +102,8 @@ status: "community" # Your Name ``` +> **Note**: The `avatar_url` should point to your avatar image relative to your namespace directory. + ### 2. Generate Module Files ```bash @@ -124,7 +139,7 @@ resource "coder_script" "install" { **Update `README.md`** - Add proper frontmatter: -````markdown +```markdown --- display_name: "Tool Name" description: "Brief description of what this module does" @@ -147,9 +162,7 @@ module "tool" { agent_id = coder_agent.main.id } ``` -```` - -```` +``` **Write tests in `main.test.ts`**: ```typescript @@ -167,7 +180,7 @@ describe("module-name", () => { }); }); }); -```` +``` ### 4. Test and Submit @@ -259,25 +272,16 @@ bun test - What you changed and why - Any breaking changes -### PR Template +### Using PR Templates -```markdown -## Description +We have different PR templates for different types of contributions. GitHub will show you options to choose from, or you can manually select: -Brief description of changes. +- **New Module**: Use `?template=new_module.md` +- **Bug Fix**: Use `?template=bug_fix.md` +- **Feature**: Use `?template=feature.md` +- **Documentation**: Use `?template=documentation.md` -## Type of Change - -- [ ] New module -- [ ] Bug fix -- [ ] Feature enhancement -- [ ] Documentation - -## Testing - -- [ ] Tests pass (`bun test`) -- [ ] Code formatted (`bun run fmt`) -``` +Example: `https://github.com/coder/registry/compare/main...your-branch?template=new_module.md` --- @@ -331,24 +335,15 @@ go build ./cmd/readmevalidation && ./readmevalidation --- -## Release Process - -After your PR is merged, maintainers will handle the release: - -1. **Create release tags** for changed modules: - - ```bash - git tag -a "release/$namespace/$module/v$version" -m "Release $namespace/$module v$version" - git push origin release/$namespace/$module/v$version - ``` +## Versioning Guidelines -2. **Version numbers** follow semantic versioning: +After your PR is merged, maintainers will handle the release. Understanding version numbers helps you describe the impact of your changes: - - **Patch** (1.2.3 → 1.2.4): Bug fixes - - **Minor** (1.2.3 → 1.3.0): New features, adding inputs - - **Major** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing types) +- **Patch** (1.2.3 → 1.2.4): Bug fixes +- **Minor** (1.2.3 → 1.3.0): New features, adding inputs +- **Major** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing types) -3. **Publishing**: Changes are automatically published to [registry.coder.com](https://registry.coder.com) after tags are pushed. +**Important**: Always specify the version change in your PR (e.g., `v1.2.3 → v1.2.4`). This helps maintainers create the correct release tag. --- From 872b8a1ee60e626c8c55f73947c9812b0a83970c Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Thu, 29 May 2025 02:12:37 +0000 Subject: [PATCH 08/26] docs(MAINTAINER): Update maintainer guidelines to include versioning and avatar image requirements --- MAINTAINER.md | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/MAINTAINER.md b/MAINTAINER.md index 1a861cc28..00e1ca637 100644 --- a/MAINTAINER.md +++ b/MAINTAINER.md @@ -24,6 +24,17 @@ Check that PRs have: - [ ] Proper frontmatter in README - [ ] Working tests (`bun test`) - [ ] Formatted code (`bun run fmt`) +- [ ] Avatar image for new namespaces (in `images/` directory) + +#### Version Guidelines + +When reviewing PRs, ensure the version change follows semantic versioning: + +- **Patch** (1.2.3 → 1.2.4): Bug fixes +- **Minor** (1.2.3 → 1.3.0): New features, adding inputs +- **Major** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing types) + +PRs should clearly indicate the version change (e.g., `v1.2.3 → v1.2.4`). ### Validate READMEs @@ -37,17 +48,23 @@ go build ./cmd/readmevalidation && ./readmevalidation After merging a PR: +1. Get the new version from the PR (shown as `old → new`) +2. Checkout the merge commit and create the tag: + ```bash +# Checkout the merge commit git checkout MERGE_COMMIT_ID + +# Create and push the release tag using the version from the PR git tag -a "release/$namespace/$module/v$version" -m "Release $namespace/$module v$version" git push origin release/$namespace/$module/v$version ``` -### Version Numbers +Example: If PR shows `v1.2.3 → v1.2.4`, use `v1.2.4` in the tag. -- **Patch** (1.2.3 → 1.2.4): Bug fixes -- **Minor** (1.2.3 → 1.3.0): New features, adding inputs -- **Major** (1.2.3 → 2.0.0): Breaking changes +### Publishing + +Changes are automatically published to [registry.coder.com](https://registry.coder.com) after tags are pushed. ## README Requirements @@ -67,6 +84,7 @@ tags: ["tag1", "tag2"] ```yaml display_name: "Your Name" bio: "Brief description" +avatar_url: "./images/avatar.png" # Path to avatar image github: "username" status: "community" # or "partner", "official" ``` @@ -77,13 +95,4 @@ status: "community" # or "partner", "official" - **Tests fail**: Ensure Docker with `--network=host`, check Terraform syntax - **Wrong file structure**: Use `./scripts/new_module.sh` for new modules -## Emergency - -### Revert Release - -```bash -git tag -d release/$namespace/$module/v$version -git push origin :refs/tags/release/$namespace/$module/v$version -``` - That's it. Keep it simple. From aa8f941e2523a5de2c8e86cd20f0a45afebdc069 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Thu, 29 May 2025 02:14:05 +0000 Subject: [PATCH 09/26] feat(PR Templates): Add new pull request templates for bug fixes, features, documentation, and new modules --- .github/PULL_REQUEST_TEMPLATE.md | 17 +++++++++++++ .github/PULL_REQUEST_TEMPLATE/bug_fix.md | 18 +++++++++++++ .../PULL_REQUEST_TEMPLATE/documentation.md | 18 +++++++++++++ .github/PULL_REQUEST_TEMPLATE/feature.md | 25 +++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE/new_module.md | 21 ++++++++++++++++ 5 files changed, 99 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/bug_fix.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/documentation.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/feature.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/new_module.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..a1e8b3853 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ +## Choose a PR Template + +Please select the appropriate PR template for your contribution: + +- 🆕 [New Module](?template=new_module.md) - Adding a new module to the registry +- 🐛 [Bug Fix](?template=bug_fix.md) - Fixing an existing issue +- ✨ [Feature](?template=feature.md) - Adding new functionality to a module +- 📝 [Documentation](?template=documentation.md) - Improving docs only + +--- + +If you've already started your PR, add `?template=TEMPLATE_NAME.md` to your URL. + +### Quick Checklist +- [ ] Tests pass (`bun test`) +- [ ] Code formatted (`bun run fmt`) +- [ ] Following contribution guidelines \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE/bug_fix.md b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md new file mode 100644 index 000000000..fc0d670a0 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md @@ -0,0 +1,18 @@ +## Bug Fix: [Brief Description] + +**Module:** `registry/[namespace]/modules/[module-name]` +**Version:** `v1.2.3` → `v1.2.4` + +### Problem + + +### Solution + + +### Testing +- [ ] Tests pass (`bun test`) +- [ ] Code formatted (`bun run fmt`) +- [ ] Fix verified locally + +### Related Issue + \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE/documentation.md b/.github/PULL_REQUEST_TEMPLATE/documentation.md new file mode 100644 index 000000000..9babaabb1 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/documentation.md @@ -0,0 +1,18 @@ +## Documentation Update + +### Description + + +### Changes + +- +- + +### Checklist +- [ ] README validation passes (if applicable) +- [ ] Code examples tested +- [ ] Links verified +- [ ] Formatting consistent + +### Context + \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE/feature.md b/.github/PULL_REQUEST_TEMPLATE/feature.md new file mode 100644 index 000000000..c5474f068 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/feature.md @@ -0,0 +1,25 @@ +## Feature: [Brief Description] + +**Module:** `registry/[namespace]/modules/[module-name]` +**Version:** `v1.2.3` → `v1.3.0` (or `v2.0.0` for breaking changes) + +### Description + + +### Changes + +- +- + +### Breaking Changes + +- None / *Remove if not applicable* + +### Testing +- [ ] Tests pass (`bun test`) +- [ ] Code formatted (`bun run fmt`) +- [ ] New tests added for feature +- [ ] Backward compatibility maintained + +### Documentation + \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE/new_module.md b/.github/PULL_REQUEST_TEMPLATE/new_module.md new file mode 100644 index 000000000..ee87860a2 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/new_module.md @@ -0,0 +1,21 @@ +## New Module: [Module Name] + +**Module Path:** `registry/[namespace]/modules/[module-name]` +**Initial Version:** `v1.0.0` + +### Description + + +### Checklist +- [ ] All required files included (`main.tf`, `main.test.ts`, `README.md`) +- [ ] Tests pass (`bun test`) +- [ ] Code formatted (`bun run fmt`) +- [ ] README has proper frontmatter +- [ ] Icon path is valid +- [ ] Namespace has avatar (if first-time contributor) + +### Testing + + +### Additional Notes + \ No newline at end of file From 5223c579cc665d2c8095d2e5f48c170c129bd140 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Thu, 29 May 2025 02:24:20 +0000 Subject: [PATCH 10/26] docs(CONTRIBUTING): Update image and avatar guidelines for namespace structure and README frontmatter requirements --- CONTRIBUTING.md | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43cfac0e3..0114ce9de 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,9 +61,9 @@ All modules are organized under `/registry/[namespace]/modules/`. Each contribut ### Images and Icons -- **Namespace avatars**: Place your avatar in `/registry/[namespace]/images/` -- **Module images**: Place other images in `/registry/[namespace]/images/` to avoid conflicts -- **Module icons**: Can go in the top-level `/.icons/` directory if used by multiple modules +- **Namespace avatars**: Must be named `avatar.png` or `avatar.svg` in `/registry/[namespace]/.images/` +- **Module screenshots/demos**: Use `/registry/[namespace]/.images/` for module-specific images +- **Module icons**: Use the shared `/.icons/` directory at the root for module icons --- @@ -75,16 +75,16 @@ If you're a new contributor, create your namespace: ```bash mkdir -p registry/[your-username] -mkdir -p registry/[your-username]/images +mkdir -p registry/[your-username]/.images ``` #### Add Your Avatar -Every namespace should have an avatar. Add your avatar image: +Every namespace must have an avatar. Add your avatar image: -1. Add a square image (recommended: 400x400px minimum) to `registry/[your-username]/images/` -2. Supported formats: `.png`, `.jpg`, `.jpeg`, `.svg` -3. Name it something clear like `avatar.png` or `profile.jpg` +1. Add a square image (recommended: 400x400px minimum) to `registry/[your-username]/.images/` +2. Name it exactly `avatar.png` or `avatar.svg` +3. Supported formats: `.png` or `.svg` only #### Create Your Namespace README @@ -93,16 +93,21 @@ Create `registry/[your-username]/README.md`: ```markdown --- display_name: "Your Name" -bio: "Brief description of what you do" -avatar_url: "./images/avatar.png" +bio: "Brief description of who you are and what you do" +avatar_url: "./.images/avatar.png" github: "your-username" +linkedin: "https://www.linkedin.com/in/your-username" # Optional +website: "https://yourwebsite.com" # Optional +support_email: "you@example.com" # Optional status: "community" --- # Your Name + +Brief description of who you are and what you do. ``` -> **Note**: The `avatar_url` should point to your avatar image relative to your namespace directory. +> **Note**: The `avatar_url` must point to `./.images/avatar.png` or `./.images/avatar.svg`. ### 2. Generate Module Files @@ -143,7 +148,7 @@ resource "coder_script" "install" { --- display_name: "Tool Name" description: "Brief description of what this module does" -icon: "../../../.icons/tool.svg" +icon: "../../../../.icons/tool.svg" maintainer_github: "your-username" verified: false tags: ["development", "tool"] @@ -166,15 +171,17 @@ module "tool" { **Write tests in `main.test.ts`**: ```typescript +import { describe, expect, it } from "bun:test"; import { runTerraformApply, runTerraformInit, testRequiredVariables } from "~test"; -describe("module-name", () => { +describe("module-name", async () => { + await runTerraformInit(import.meta.dir); + it("should have required variables", async () => { await testRequiredVariables(import.meta.dir); }); it("should apply successfully", async () => { - await runTerraformInit(import.meta.dir); await runTerraformApply(import.meta.dir, { agent_id: "test-agent-id", }); @@ -295,15 +302,17 @@ Example: `https://github.com/coder/registry/compare/main...your-branch?template= ### README Frontmatter +Module README frontmatter must include: + ```yaml --- display_name: "Module Name" # Required - Name shown on Registry website -description: "What it does" # Required - Short description for Registry -icon: "path/to/icon.svg" # Required - Path to icon file +description: "What it does" # Required - Short description +icon: "../../../../.icons/tool.svg" # Required - Path to icon file maintainer_github: "your-username" # Required - Your GitHub username -verified: false # Optional - Set by Coder maintainers only +partner_github: "partner-name" # Optional - For official partner modules +verified: false # Optional - Set by maintainers only tags: ["tag1", "tag2"] # Required - Array of descriptive tags -partner_github: "partner-name" # Optional - For official partnerships only --- ``` From dd1606754ba9109a3600f0584570c3321f98ab59 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Thu, 29 May 2025 02:24:27 +0000 Subject: [PATCH 11/26] docs(MAINTAINER): Refine avatar image requirements and update module frontmatter guidelines --- MAINTAINER.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/MAINTAINER.md b/MAINTAINER.md index 00e1ca637..69d1a6576 100644 --- a/MAINTAINER.md +++ b/MAINTAINER.md @@ -24,7 +24,7 @@ Check that PRs have: - [ ] Proper frontmatter in README - [ ] Working tests (`bun test`) - [ ] Formatted code (`bun run fmt`) -- [ ] Avatar image for new namespaces (in `images/` directory) +- [ ] Avatar image for new namespaces (`avatar.png` or `avatar.svg` in `.images/`) #### Version Guidelines @@ -71,11 +71,12 @@ Changes are automatically published to [registry.coder.com](https://registry.cod ### Module Frontmatter (Required) ```yaml -display_name: "Tool Name" +display_name: "Module Name" description: "What it does" -icon: "path/to/icon.svg" +icon: "../../../../.icons/tool.svg" maintainer_github: "username" -verified: false # true for verified modules +partner_github: "partner-name" # Optional - For official partner modules +verified: false # Optional - Set by maintainers only tags: ["tag1", "tag2"] ``` @@ -83,9 +84,12 @@ tags: ["tag1", "tag2"] ```yaml display_name: "Your Name" -bio: "Brief description" -avatar_url: "./images/avatar.png" # Path to avatar image +bio: "Brief description of who you are and what you do" +avatar_url: "./.images/avatar.png" github: "username" +linkedin: "https://www.linkedin.com/in/username" # Optional +website: "https://yourwebsite.com" # Optional +support_email: "you@example.com" # Optional status: "community" # or "partner", "official" ``` @@ -94,5 +98,6 @@ status: "community" # or "partner", "official" - **README validation fails**: Check YAML syntax, ensure h1 header after frontmatter - **Tests fail**: Ensure Docker with `--network=host`, check Terraform syntax - **Wrong file structure**: Use `./scripts/new_module.sh` for new modules +- **Missing namespace avatar**: Must be `avatar.png` or `avatar.svg` in `.images/` directory That's it. Keep it simple. From 33047dbf4540b29bbcb2b8455f5060c54d6b8976 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Thu, 29 May 2025 02:30:28 +0000 Subject: [PATCH 12/26] docs(CONTRIBUTING): Revise module building instructions for clarity and structure --- CONTRIBUTING.md | 81 +++++++------------------------------------------ 1 file changed, 11 insertions(+), 70 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0114ce9de..fe7418fa1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -116,78 +116,19 @@ Brief description of who you are and what you do. cd registry/[your-username]/modules/[module-name] ``` -### 3. Build Your Module - -**Edit `main.tf`** - Your Terraform code: - -```terraform -terraform { - required_version = ">= 1.0" - required_providers { - coder = { - source = "coder/coder" - version = ">= 0.17" - } - } -} - -variable "agent_id" { - description = "The ID of a Coder agent." - type = string -} - -resource "coder_script" "install" { - agent_id = var.agent_id - script = file("${path.module}/run.sh") -} -``` - -**Update `README.md`** - Add proper frontmatter: - -```markdown ---- -display_name: "Tool Name" -description: "Brief description of what this module does" -icon: "../../../../.icons/tool.svg" -maintainer_github: "your-username" -verified: false -tags: ["development", "tool"] ---- - -# Tool Name +This script generates: +- `main.tf` - Terraform configuration template +- `README.md` - Documentation template with frontmatter -Brief description and usage example. - -## Usage - -```tf -module "tool" { - source = "registry.coder.com/[username]/[module]/coder" - version = "1.0.0" - agent_id = coder_agent.main.id -} -``` -``` - -**Write tests in `main.test.ts`**: -```typescript -import { describe, expect, it } from "bun:test"; -import { runTerraformApply, runTerraformInit, testRequiredVariables } from "~test"; - -describe("module-name", async () => { - await runTerraformInit(import.meta.dir); - - it("should have required variables", async () => { - await testRequiredVariables(import.meta.dir); - }); +### 3. Build Your Module - it("should apply successfully", async () => { - await runTerraformApply(import.meta.dir, { - agent_id: "test-agent-id", - }); - }); -}); -``` +1. **Edit `main.tf`** to implement your module's functionality +2. **Update `README.md`** with: + - Accurate description and usage examples + - Correct icon path (usually `../../../../.icons/your-icon.svg`) + - Proper tags that describe your module +3. **Create `main.test.ts`** to test your module +4. **Add any scripts** or additional files your module needs ### 4. Test and Submit From 9a0b12f759946842965ebe7727523c1e2275fab3 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Thu, 29 May 2025 02:32:24 +0000 Subject: [PATCH 13/26] docs: Prettier Formatting --- .github/PULL_REQUEST_TEMPLATE.md | 3 ++- .github/PULL_REQUEST_TEMPLATE/bug_fix.md | 6 +++++- .github/PULL_REQUEST_TEMPLATE/documentation.md | 11 ++++++++--- .github/PULL_REQUEST_TEMPLATE/feature.md | 15 +++++++++++---- .github/PULL_REQUEST_TEMPLATE/new_module.md | 6 +++++- CONTRIBUTING.md | 3 ++- 6 files changed, 33 insertions(+), 11 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a1e8b3853..9c13c11d9 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,6 +12,7 @@ Please select the appropriate PR template for your contribution: If you've already started your PR, add `?template=TEMPLATE_NAME.md` to your URL. ### Quick Checklist + - [ ] Tests pass (`bun test`) - [ ] Code formatted (`bun run fmt`) -- [ ] Following contribution guidelines \ No newline at end of file +- [ ] Following contribution guidelines diff --git a/.github/PULL_REQUEST_TEMPLATE/bug_fix.md b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md index fc0d670a0..c9a53217a 100644 --- a/.github/PULL_REQUEST_TEMPLATE/bug_fix.md +++ b/.github/PULL_REQUEST_TEMPLATE/bug_fix.md @@ -4,15 +4,19 @@ **Version:** `v1.2.3` → `v1.2.4` ### Problem + ### Solution + ### Testing + - [ ] Tests pass (`bun test`) - [ ] Code formatted (`bun run fmt`) - [ ] Fix verified locally ### Related Issue - \ No newline at end of file + + diff --git a/.github/PULL_REQUEST_TEMPLATE/documentation.md b/.github/PULL_REQUEST_TEMPLATE/documentation.md index 9babaabb1..32031022b 100644 --- a/.github/PULL_REQUEST_TEMPLATE/documentation.md +++ b/.github/PULL_REQUEST_TEMPLATE/documentation.md @@ -1,18 +1,23 @@ ## Documentation Update ### Description + ### Changes + -- -- + +- +- ### Checklist + - [ ] README validation passes (if applicable) - [ ] Code examples tested - [ ] Links verified - [ ] Formatting consistent ### Context - \ No newline at end of file + + diff --git a/.github/PULL_REQUEST_TEMPLATE/feature.md b/.github/PULL_REQUEST_TEMPLATE/feature.md index c5474f068..b666cc991 100644 --- a/.github/PULL_REQUEST_TEMPLATE/feature.md +++ b/.github/PULL_REQUEST_TEMPLATE/feature.md @@ -4,22 +4,29 @@ **Version:** `v1.2.3` → `v1.3.0` (or `v2.0.0` for breaking changes) ### Description + ### Changes + -- -- + +- +- ### Breaking Changes + -- None / *Remove if not applicable* + +- None / _Remove if not applicable_ ### Testing + - [ ] Tests pass (`bun test`) - [ ] Code formatted (`bun run fmt`) - [ ] New tests added for feature - [ ] Backward compatibility maintained ### Documentation - \ No newline at end of file + + diff --git a/.github/PULL_REQUEST_TEMPLATE/new_module.md b/.github/PULL_REQUEST_TEMPLATE/new_module.md index ee87860a2..dd0f84276 100644 --- a/.github/PULL_REQUEST_TEMPLATE/new_module.md +++ b/.github/PULL_REQUEST_TEMPLATE/new_module.md @@ -4,9 +4,11 @@ **Initial Version:** `v1.0.0` ### Description + ### Checklist + - [ ] All required files included (`main.tf`, `main.test.ts`, `README.md`) - [ ] Tests pass (`bun test`) - [ ] Code formatted (`bun run fmt`) @@ -15,7 +17,9 @@ - [ ] Namespace has avatar (if first-time contributor) ### Testing + ### Additional Notes - \ No newline at end of file + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe7418fa1..66b644c33 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -117,6 +117,7 @@ cd registry/[your-username]/modules/[module-name] ``` This script generates: + - `main.tf` - Terraform configuration template - `README.md` - Documentation template with frontmatter @@ -224,7 +225,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 Module**: Use `?template=new_module.md` - **Bug Fix**: Use `?template=bug_fix.md` - **Feature**: Use `?template=feature.md` - **Documentation**: Use `?template=documentation.md` From b0e16cc1bd31cdeb3d8f6134a12c5341f5454baa Mon Sep 17 00:00:00 2001 From: DevCats Date: Fri, 30 May 2025 12:09:40 -0500 Subject: [PATCH 14/26] Update CONTRIBUTING.md - remove unneeded Git reference Co-authored-by: Atif Ali --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 66b644c33..4d8747a08 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,7 +16,6 @@ The Coder Registry is a collection of Terraform modules that extend Coder worksp ### Prerequisites -- Git and GitHub account - Basic Terraform knowledge (for module development) - Terraform installed ([installation guide](https://developer.hashicorp.com/terraform/install)) - Docker (for running tests) From 01c9a491af9c60977903d174beeb90be4b89cd59 Mon Sep 17 00:00:00 2001 From: DevCats Date: Fri, 30 May 2025 12:10:09 -0500 Subject: [PATCH 15/26] Update CONTRIBUTING.md remove (test runner) indication Co-authored-by: Atif Ali --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d8747a08..0c18fc566 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,7 +22,7 @@ The Coder Registry is a collection of Terraform modules that extend Coder worksp ### Install Dependencies -Install Bun (test runner): +Install Bun: ```bash curl -fsSL https://bun.sh/install | bash From 1ebaa9dc96aeca5754b5128341741a78c5251b0f Mon Sep 17 00:00:00 2001 From: DevCats Date: Fri, 30 May 2025 12:10:30 -0500 Subject: [PATCH 16/26] Update CONTRIBUTING.md dropping term restart for bun Co-authored-by: Atif Ali --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c18fc566..666e7b72c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,7 +28,6 @@ Install Bun: curl -fsSL https://bun.sh/install | bash ``` -Restart your terminal or source your profile: ```bash source ~/.bashrc From 9faf827048c33df17be8c67aed94bdd91a7397e1 Mon Sep 17 00:00:00 2001 From: DevCats Date: Fri, 30 May 2025 12:10:56 -0500 Subject: [PATCH 17/26] Update CONTRIBUTING.md command is echoed in consol remove unneeded step Co-authored-by: Atif Ali --- CONTRIBUTING.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 666e7b72c..4e2bd1820 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,9 +29,6 @@ curl -fsSL https://bun.sh/install | bash ``` -```bash -source ~/.bashrc -``` Install project dependencies: From 673aa0d0c6faefb8c70f6fd7bad7f07e3206d12e Mon Sep 17 00:00:00 2001 From: DevCats Date: Fri, 30 May 2025 12:11:29 -0500 Subject: [PATCH 18/26] Update CONTRIBUTING.md - remove yarn warning Co-authored-by: Atif Ali --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e2bd1820..a755a09a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,6 @@ Install project dependencies: bun install ``` -> **Note**: This repository does not support Yarn. Please use Bun for all package management. ### Installing Go (Optional) From 348e68e0246f0e8caa74ea42bc6d6d332149e51d Mon Sep 17 00:00:00 2001 From: DevCats Date: Fri, 30 May 2025 12:11:51 -0500 Subject: [PATCH 19/26] Update CONTRIBUTING.md bun run fmt to bun fmt Co-authored-by: Atif Ali --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a755a09a3..9edf6d62f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -132,7 +132,7 @@ This script generates: bun test # Format code -bun run fmt +bun fmt # Commit and create PR git add . From ace0498eb4b0db90dce77a4a0e4887962e8bf849 Mon Sep 17 00:00:00 2001 From: DevCats Date: Fri, 30 May 2025 12:12:10 -0500 Subject: [PATCH 20/26] Update CONTRIBUTING.md remove stale frontmatter Co-authored-by: Atif Ali --- CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9edf6d62f..d3ab18548 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -245,8 +245,6 @@ Module README frontmatter must include: display_name: "Module Name" # Required - Name shown on Registry website description: "What it does" # Required - Short description icon: "../../../../.icons/tool.svg" # Required - Path to icon file -maintainer_github: "your-username" # Required - Your GitHub username -partner_github: "partner-name" # Optional - For official partner modules verified: false # Optional - Set by maintainers only tags: ["tag1", "tag2"] # Required - Array of descriptive tags --- From 78fd9957574d024255c06c0272ed4a628947df5f Mon Sep 17 00:00:00 2001 From: DevCats Date: Fri, 30 May 2025 12:12:43 -0500 Subject: [PATCH 21/26] Update CONTRIBUTING.md bun run fmt to bun fmt Co-authored-by: Atif Ali --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3ab18548..2bacd1aba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -314,6 +314,6 @@ When reporting bugs, include: 2. **No tests** or broken tests 3. **Hardcoded values** instead of variables 4. **Breaking changes** without defaults -5. **Not running** `bun run fmt` before submitting +5. **Not running** `bun fmt` before submitting Happy contributing! 🚀 From 4fd5ab3d2f220eeb7855934debecd3c023b6bd5c Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Sat, 31 May 2025 02:04:57 +0000 Subject: [PATCH 22/26] docs:(CONTRIBUTING.md) Add note about `run.sh` script for module execution --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2bacd1aba..684b2a7e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -114,6 +114,7 @@ This script generates: - `main.tf` - Terraform configuration template - `README.md` - Documentation template with frontmatter +- `run.sh` - Script for module execution (can be deleted if not required) ### 3. Build Your Module From c6f78f5e11b8fdc9f0f9392fc070db4f3e80b14d Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Sat, 31 May 2025 02:09:35 +0000 Subject: [PATCH 23/26] docs:(CONTRIBUTING.md) Remove optional Go installation section and README validation since this is for maintainers --- CONTRIBUTING.md | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 684b2a7e5..bd20404d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,27 +28,12 @@ Install Bun: curl -fsSL https://bun.sh/install | bash ``` - - Install project dependencies: ```bash bun install ``` - -### Installing Go (Optional) - -This step can be skipped if you are not working on any of the README validation logic. The validation will still run as part of CI. - -Navigate to the [official Go installation page](https://golang.org/doc/install), and install the correct version for your operating system. - -Once Go has been installed, verify the installation: - -```bash -go version -``` - ### 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. @@ -269,16 +254,6 @@ All README files must follow these rules: --- -## README Validation - -If you installed Go, you can validate README files locally: - -```bash -go build ./cmd/readmevalidation && ./readmevalidation -``` - ---- - ## Versioning Guidelines After your PR is merged, maintainers will handle the release. Understanding version numbers helps you describe the impact of your changes: From b6bf53a803d8b7871e964b6e7eb0a3fd714ed5fd Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Sat, 31 May 2025 02:16:49 +0000 Subject: [PATCH 24/26] docs(CONTRIBUTING): Update testing instructions to specify module name for bun test command --- CONTRIBUTING.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd20404d6..36ea6dd05 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -115,7 +115,7 @@ This script generates: ```bash # Test your module -bun test +bun test -t 'module-name' # Format code bun fmt @@ -163,12 +163,10 @@ find registry -name "*[module-name]*" -type d ### 3. Test Your Changes ```bash -cd registry/[namespace]/modules/[module-name] - -# Test the specific module -bun test +# Test a specific module +bun test -t 'module-name' -# Test all modules (from repo root) +# Test all modules bun test ``` From 1fee632c64e4aac561f8fef4614b01f484eb6bf7 Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Mon, 2 Jun 2025 23:08:50 +0000 Subject: [PATCH 25/26] docs(CONTRIBUTING): Update avatar instructions to recommend using GitHub avatar and clarify image requirements --- CONTRIBUTING.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 060c7c8d0..590c2afc2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,11 +59,16 @@ mkdir -p registry/[your-username]/.images #### Add Your Avatar -Every namespace must have an avatar. Add your avatar image: +Every namespace must have an avatar. We recommend using your GitHub avatar: -1. Add a square image (recommended: 400x400px minimum) to `registry/[your-username]/.images/` -2. Name it exactly `avatar.png` or `avatar.svg` -3. Supported formats: `.png` or `.svg` only +1. Download your GitHub avatar from `https://github.com/[your-username].png` +2. Save it as `avatar.png` in `registry/[your-username]/.images/` +3. This gives you a properly sized, square image that's already familiar to the community + +The avatar must be: +- Named exactly `avatar.png` or `avatar.svg` +- Square image (recommended: 400x400px minimum) +- Supported formats: `.png` or `.svg` only #### Create Your Namespace README From 3ee65d4016cfbe0bb7ba2d119766826450cf267f Mon Sep 17 00:00:00 2001 From: DevelopmentCats Date: Mon, 2 Jun 2025 23:14:00 +0000 Subject: [PATCH 26/26] docs(CONTRIBUTING): Prettier Formatting --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 590c2afc2..a0e8f6332 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,6 +66,7 @@ Every namespace must have an avatar. We recommend using your GitHub avatar: 3. This gives you a properly sized, square image that's already familiar to the community The avatar must be: + - Named exactly `avatar.png` or `avatar.svg` - Square image (recommended: 400x400px minimum) - Supported formats: `.png` or `.svg` only