Maintainer Guide

Quick reference for maintaining the Coder Registry repository.

Setup

Install Go for README validation:

# macOS
brew install go

# Linux
sudo apt install golang-go

Daily Tasks

Review PRs

Check that PRs have:

All required files (main.tf, main.test.ts, README.md)
Proper frontmatter in README
Working tests (bun test)
Formatted code (bun run fmt)
Avatar image for new namespaces (avatar.png or avatar.svg in .images/)

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

go build ./cmd/readmevalidation && ./readmevalidation

Releases

Create Release Tags

After merging a PR:

Get the new version from the PR (shown as old → new)
Checkout the merge commit and create the tag:

# 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

Example: If PR shows v1.2.3 → v1.2.4, use v1.2.4 in the tag.

Publishing

Changes are automatically published to registry.coder.com after tags are pushed.

README Requirements

Module Frontmatter (Required)

display_name: "Module Name"
description: "What it does"
icon: "../../../../.icons/tool.svg"
maintainer_github: "username"
partner_github: "partner-name" # Optional - For official partner modules
verified: false # Optional - Set by maintainers only
tags: ["tag1", "tag2"]

Namespace Frontmatter (Required)

display_name: "Your Name"
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"

Common Issues

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.