Skip to content

Coding Standards

These coding standards ensure consistency and quality across the OpenBao Operator codebase. All contributors—human or AI-assisted—must follow these guidelines.

Guiding Principle: "Clear is better than clever." We prioritize readability, maintainability, and explicit error handling over terse or "magical" code.

Standards Directory

  • Go Style

    Formatting, naming conventions, and idiomatic Go usage.

    Read Guide

  • Error Handling

    Proper error wrapping, checking, and defining well-known errors.

    Read Guide

  • Generated Artifacts

    Handling auto-generated code (CRDs, DeepCopy, RBAC).

    Read Guide

  • K8s Patterns

    Operator best practices: idempotency, context, and status updates.

    Read Guide

  • Security Practices

    Secure coding, input validation, and secrets handling.

    Read Guide

  • Conventions

    Project-specific rules for metrics, logging, and extensive testing.

    Read Guide

  • Conventional Commits

    Standardized commit messages for automated changelogs.

    Read Guide

Quick Reference

The Golden Rules

Must Do

  • Format Code: Always run gofmt or goimports.
  • Linting: Pass golangci-lint with the default configuration.
  • Wrap Errors: Use fmt.Errorf("...: %w", err) to preserve context.
  • Structured Logs: Use log.Info("msg", "key", "value") instead of Printf.
  • Test Logic: Write table-driven unit tests for all business logic.
  • Verify: Run the full check suite: make lint verify-fmt verify-tidy verify-generated verify-helm test-ci

Must NOT Do

  • No interface{}: Avoid any types without rigorous justification.
  • No Secret Logs: Never log keys, tokens, or passwords.
  • No Blockers: Do NOT use time.Sleep() in reconcilers. Use RequeueAfter.
  • No RBAC Annotations: Do NOT use +kubebuilder:rbac on the Cluster controller.
  • No Shelling Out: Do NOT exec out to kubectl or CLI tools; use Go libraries.

See Also