From d21f55a322df8e6e03ca0e4e2d4ae9d4339d1a7d Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Tue, 20 Jan 2026 12:59:15 +0500 Subject: [PATCH] chore: update AGENTS.md with commands and PR review checklist (#663) ## Description Updates AGENTS.md to be more concise (~36 lines) while adding missing commands and a PR review checklist based on recent PR feedback. ## Changes - **Commands section**: Added `bun run tftest`, `bun run tstest`, single test commands, and version-bump script - **Structure section**: Added note that URLs must be relative (from #639) - **Code Style section**: Added `tf` vs `hcl` guidance and relative icon paths - **New PR Review Checklist**: Based on patterns from recent PRs including: - Version bumping requirements (#661, #617) - Breaking changes documentation (#636) - Graceful error handling in scripts (#658) - Diagnostic logging for tests (#643) - **AI attribution requirement**: PRs should note model/tool used ## Type of Change - [ ] New module - [ ] New template - [ ] Bug fix - [ ] Feature/enhancement - [x] Documentation - [ ] Other --- Generated with [Amp](https://ampcode.com/threads/T-019bcb7e-2e92-76f2-a1aa-2023ecdb0763) using Claude Sonnet 4 --- AGENTS.md | 185 +++++++++--------------------------------------------- 1 file changed, 29 insertions(+), 156 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bc69ef4a..42ac3ed2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,168 +1,41 @@ # AGENTS.md -This file provides guidance to AI coding assistants when working with code in this repository. +Coder Registry: Terraform modules/templates for Coder workspaces under `registry/[namespace]/modules/` and `registry/[namespace]/templates/`. -## Project Overview - -The Coder Registry is a community-driven repository for Terraform modules and templates that extend Coder workspaces. It's organized with: - -- **Modules**: Individual components and tools (IDEs, auth integrations, dev tools) -- **Templates**: Complete workspace configurations for different platforms -- **Namespaces**: Each contributor has their own namespace under `/registry/[namespace]/` - -## Common Development Commands - -### Formatting +## Commands ```bash -bun run fmt # Format all code (Prettier + Terraform) -bun run fmt:ci # Check formatting (CI mode) +bun run fmt # Format code (Prettier + Terraform) - run before commits +bun run tftest # Run all Terraform tests +bun run tstest # Run all TypeScript tests +terraform init -upgrade && terraform test -verbose # Test single module (run from module dir) +bun test main.test.ts # Run single TS test (from module dir) +./scripts/terraform_validate.sh # Validate Terraform syntax +./scripts/new_module.sh ns/name # Create new module scaffold +.github/scripts/version-bump.sh patch | minor | major # Bump module version after changes ``` -### Testing +## Structure -```bash -# Test all modules with .tftest.hcl files -bun run test +- **Modules**: `registry/[ns]/modules/[name]/` with `main.tf`, `README.md` (YAML frontmatter), `.tftest.hcl` (required) +- **Templates**: `registry/[ns]/templates/[name]/` with `main.tf`, `README.md` +- **Validation**: `cmd/readmevalidation/` (Go) validates structure/frontmatter; URLs must be relative, not absolute -# Test specific module (from module directory) -terraform init -upgrade -terraform test -verbose +## Code Style -# Validate Terraform syntax -./scripts/terraform_validate.sh -``` +- Every module MUST have `.tftest.hcl` tests; optional `main.test.ts` for container/script tests +- README frontmatter: `display_name`, `description`, `icon`, `verified: false`, `tags` +- Use semantic versioning; bump version via script when modifying modules +- Docker tests require Linux or Colima/OrbStack (not Docker Desktop) +- Use `tf` (not `hcl`) for code blocks in README; use relative icon paths (e.g., `../../../../.icons/`) -### Module Creation +## PR Review Checklist -```bash -# Generate new module scaffold -./scripts/new_module.sh namespace/module-name -``` - -### TypeScript Testing & Setup - -The repository uses Bun for TypeScript testing with utilities: - -- `test/test.ts` - Testing utilities for container management and Terraform operations -- `setup.ts` - Test cleanup (removes .tfstate files and test containers) -- Container-based testing with Docker for module validation - -## Architecture & Organization - -### Directory Structure - -``` -registry/[namespace]/ -├── README.md # Contributor info with frontmatter -├── .images/ # Namespace avatar (avatar.png/svg) -├── modules/ # Individual components -│ └── [module]/ # Each module has main.tf, README.md, tests -└── templates/ # Complete workspace configs - └── [template]/ # Each template has main.tf, README.md -``` - -### Key Components - -**Module Structure**: Each module contains: - -- `main.tf` - Terraform implementation -- `README.md` - Documentation with YAML frontmatter -- `.tftest.hcl` - Terraform test files (required) -- `run.sh` - Optional startup script - -**Template Structure**: Each template contains: - -- `main.tf` - Complete Coder template configuration -- `README.md` - Documentation with YAML frontmatter -- Additional configs, scripts as needed - -### README Frontmatter Requirements - -All modules/templates require YAML frontmatter: - -```yaml ---- -display_name: "Module Name" -description: "Brief description" -icon: "../../../../.icons/tool.svg" -verified: false -tags: ["tag1", "tag2"] ---- -``` - -## Testing Requirements - -### Module Testing - -- Every module MUST have `.tftest.hcl` test files -- Optional `main.test.ts` files for container-based testing or complex business logic validation -- Tests use Docker containers with `--network=host` flag -- Linux required for testing (Docker Desktop on macOS/Windows won't work) -- Use Colima or OrbStack on macOS instead of Docker Desktop - -### Test Utilities - -The `test/test.ts` file provides: - -- `runTerraformApply()` - Execute Terraform with variables -- `executeScriptInContainer()` - Run coder_script resources in containers -- `testRequiredVariables()` - Validate required variables -- Container management functions - -## Validation & Quality - -### Automated Validation - -The Go validation tool (`cmd/readmevalidation/`) checks: - -- Repository structure integrity -- Contributor README files -- Module and template documentation -- Frontmatter format compliance - -### Versioning - -Use semantic versioning for modules: - -- **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 - -## Dependencies & Tools - -### Required Tools - -- **Terraform** - Module development and testing -- **Docker** - Container-based testing -- **Bun** - JavaScript runtime for formatting/scripts -- **Go 1.23+** - Validation tooling - -### Development Dependencies - -- Prettier with Terraform and shell plugins -- TypeScript for test utilities -- Various npm packages for documentation processing - -## Workflow Notes - -### Contributing Process - -1. Create namespace (first-time contributors) -2. Generate module/template files using scripts -3. Implement functionality and tests -4. Run formatting and validation -5. Submit PR with appropriate template - -### Testing Workflow - -- All modules must pass `terraform test` -- Use `bun run test` for comprehensive testing -- Format code with `bun run fmt` before submission -- Manual testing recommended for templates - -### Namespace Management - -- Each contributor gets unique namespace -- Namespace avatar required (avatar.png/svg in .images/) -- Namespace README with contributor info and frontmatter +- Version bumped via `.github/scripts/version-bump.sh` if module changed (patch=bugfix, minor=feature, major=breaking) +- Breaking changes documented: removed inputs, changed defaults, new required variables +- New variables have sensible defaults to maintain backward compatibility +- Tests pass (`bun run tftest`, `bun run tstest`); add diagnostic logging for test failures +- README examples updated with new version number; tooltip/behavior changes noted +- Shell scripts handle errors gracefully (use `|| echo "Warning..."` for non-fatal failures) +- No hardcoded values that should be configurable; no absolute URLs (use relative paths) +- If AI-assisted: include model and tool/agent name at footer of PR body (e.g., "Generated with [Amp](thread-url) using Claude")