bird-hk/birdhk-rule icon
public
Published on 4/1/2025
bird-hk/birdhk-rule

Rules

Build & Development Commands

  • Always use Go modules for dependency management (go mod tidy before committing).
  • Prefer make or Taskfile.yaml for automating common development tasks.
  • Use golangci-lint for static code analysis before committing.
  • When working with Kubernetes, use ko or Buildpacks for building OCI images instead of Dockerfiles when possible.
  • Use kind or k3d to create local Kubernetes clusters for testing.

Testing Guidelines

  • Write unit tests using Go's built-in testing package and table-driven tests.
  • Use testify for assertions and mocks when needed.
  • Aim for at least 80% test coverage, but focus on testing critical logic.
  • Run tests in parallel where applicable (t.Parallel()).
  • Use go test -race to detect race conditions.
  • For integration tests involving Kubernetes, prefer envtest or kind-based testing environments.

Code Style & Guidelines

  • Follow idiomatic Go practices (Effective Go and Go Proverbs).
  • Use structured logging (log/slog or zap for performance-sensitive applications).
  • Always check and handle errors properly; never ignore errors.
  • Use context (context.Context) in APIs to support timeouts and cancellations.
  • Use sync.Pool or buffer pooling for optimizing high-performance applications.
  • Avoid using global variables except for configuration or logging.
  • For cloud-native applications, prefer gRPC over REST when possible.

Documentation Guidelines

  • Document all public types, functions, and methods using GoDoc style.
  • Use README.md to provide setup and usage instructions for repositories.
  • Provide example-based documentation where applicable (examples/ directory).
  • Use OpenAPI (Swagger) for documenting RESTful APIs.
  • When writing Kubernetes CRDs, always include clear spec and status documentation.
  • Ensure Helm charts and Kubernetes manifests have proper annotations and comments.