Skip to content

AGENTS.md

Latest commit

 

History

History
130 lines (87 loc) · 3.87 KB

AGENTS.md

File metadata and controls

130 lines (87 loc) · 3.87 KB

AGENTS.md

This file provides guidelines for agents working in this repository.

Project Overview

This is the CRD Catalog - a tool that aggregates hundreds of popular Kubernetes CRDs (CustomResourceDefinition) including their JSON schema format. The catalog is used for validation (kubeconform), code generation (kopium), and language server support.

Build, Lint, and Test Commands

Running Tests

Full test suite:

make test

This runs on PRs to main via GitHub Actions (.github/workflows/tests.yaml). It includes:

  • Go unit tests with coverage
  • Schema validation
  • Smoke tests with Docker
  • Makefile linting
  • EditorConfig checks

Run Go unit tests locally:

go test ./... -timeout 10s -shuffle on -p 1 -tags containers_image_openpgp -skip 'TestCheckLocal'

Run a single test:

go test ./... -run TestName -timeout 10s

Note: -skip 'TestCheckLocal' is required because that test is for manual debugging of uncommitted configuration files and should not run in normal test execution.

Static Analysis and Formatting

Format check:

gofmt -l .

Go vet:

go vet ./...

Check for mod file changes:

go mod tidy -diff

Build

go build -o build/bin/catalog -buildvcs=false -tags containers_image_openpgp

Code Style Guidelines

Go Conventions

  • Formatting: Use gofmt (standard Go formatter). All code should be formatted before committing.
  • Language: Go (version managed automatically by GitHub workflows)
  • Testing: Uses testify/assert for assertions
  • Error handling:
    • Use sentinel errors with errors.New for defined error cases
    • Use errors.Join to combine multiple errors
  • CLI: Uses standard flag package for command-line argument parsing
  • Build tags: Required tag is containers_image_openpgp
  • Comments: Do NOT add comments unless explicitly requested

EditorConfig (Non-Go Files)

Follow the settings in .editorconfig.

GitHub Workflows

.github/dependabot.yml:

  • dependabot.yml: Weekly updates for GitHub Actions and Go module dependencies

.github/workflows/:

  • tests.yaml: Runs make test on PRs to main, auto-merges bot PRs (dependabot, crd-automation)
  • scheduled-jobs.yaml: Runs on a schedule every few hours:
    • make update - fetches CRD schemas from Helm charts
    • make comparison - compares with datreeio/CRDs-catalog
    • make tags - synchronizes Kubernetes version tags
  • upgrade-go.yaml: Weekly check for Go updates, automatically upgrades go.mod and .tool-versions via PR

Project Structure

/schema          # Generated OpenAPI schema files
/definitions     # Generated definition files (for kopium)
/configuration.yaml  # CRD sources configuration
/registry.yaml   # Tracks source versions
/internal/       # Go source code
  /command/      # CLI commands (compare, update, verify)
/make.d/         # Makefile includes
/test/           # Test fixtures and scripts

Configuration

The main configuration file is configuration.yaml. It defines CRD sources (Helm charts, URLs, etc.) that are fetched to generate the schema and definition files.

The configuration file can be validated against the JSON schema at internal/configuration/schema.json using:

go run . verify --schema internal/configuration/schema.json --file configuration.yaml

Important Notes

  • Do NOT commit changes to /schema, /definitions, registry.yaml directly - these are generated by the make update workflow
  • The .tool-versions file is managed automatically by GitHub workflows

Maintaining AGENTS.md

This file documents project conventions for agentic coding tools. Update this file to reflect changes when adding new commands, changing build processes, updating dependencies, or modifying code style conventions. Agents operating in this repository should follow the guidelines outlined here.