kopia-operator: Instructions file for GitHub Copilot

Go Development Instructions

Follow idiomatic Go practices and community standards when writing Go code. These instructions are based on Effective Go, Go Code Review Comments, and Google's Go Style Guide.

General Instructions

• Write simple, clear, and idiomatic Go code
• Favor clarity and simplicity over cleverness
• Follow the principle of least surprise
• Keep the happy path left-aligned (minimize indentation)
• Return early to reduce nesting
• Prefer early return over if-else chains; use if condition { return } pattern to avoid else blocks
• Make the zero value useful
• Write self-documenting code with clear, descriptive names
• Document exported types, functions, methods, and packages
• Use Go modules for dependency management
• Leverage the Go standard library instead of reinventing the wheel (e.g., use strings.Builder for string concatenation, filepath.Join for path construction)
• Prefer standard library solutions over custom implementations when functionality exists
• Write comments in English by default; translate only upon user request
• Avoid using emoji in code and comments

Naming Conventions

Packages

• Use lowercase, single-word package names
• Avoid underscores, hyphens, or mixedCaps
• Choose names that describe what the package provides, not what it contains
• Avoid generic names like util, common, or base
• Package names should be singular, not plural

Package Declaration Rules (CRITICAL):

• NEVER duplicate package declarations - each Go file must have exactly ONE package line
• When editing an existing .go file:
  • PRESERVE the existing package declaration - do not add another one
  • If you need to replace the entire file content, start with the existing package name
• When creating a new .go file:
  • BEFORE writing any code, check what package name other .go files in the same directory use
  • Use the SAME package name as existing files in that directory
  • If it's a new directory, use the directory name as the package name
  • Write exactly one package <name> line at the very top of the file
• When using file creation or replacement tools:
  • ALWAYS verify the target file doesn't already have a package declaration before adding one
  • If replacing file content, include only ONE package declaration in the new content
  • NEVER create files with multiple package lines or duplicate declarations