Project Conventions

Use these conventions to make a change fit the repository before CI has to rescue it.

These are the project-specific rules that go beyond generic Go style. They keep controller code predictable, reviews focused, architecture boundaries enforceable, and generated output aligned with the code that owns it.

Decision matrix

Core project conventions

Core project conventions.

Convention	What it means in practice	Why it matters
Prefer strict types	Avoid any or interface{} in core logic except where an external library leaves no alternative.	Compile-time guarantees beat runtime assertions in controller code.
Delay abstraction until the rule of three	Do not create shared helpers the first or second time a pattern appears.	This keeps the codebase from filling with speculative utility layers.
Keep PRs single-theme	A change should primarily be a feature, bug fix, refactor, or doc update, not several unrelated cleanups at once.	Smaller review surfaces keep maintainers effective.
Treat architecture boundaries as policy	Update the boundary policy before adding new top-level internal packages or controller packages.	The repository enforces these rules automatically, so design intent and CI stay aligned.
Always update the generated or test artifacts a change implies	If APIs, manifests, golden files, or rules change, regenerate them in the same PR.	Generated drift should never be left for the next contributor to discover.

No `any` in core logic

Treat any and interface{} as escape hatches for external API boundaries, not as normal implementation tools. If a helper only works because it erases types, it usually needs a narrower contract.

Type safety and package shape

• Use defined types for enum-like status and phase values instead of raw strings.
• Avoid junk-drawer package names such as util, common, or shared.
• Prefer package names that describe the actual boundary or job, such as k8sutil, config, or schema.

Review hygiene

• Keep a PR to one main theme.
• Avoid drive-by reformatting of unrelated files.
• If a change touches api/, update the generated artifacts in the same branch.

Verify

Boundary policy regeneration and verification

bash

make generate-ast-rules
make verify-arch-policy
make test-ast
make lint-ast

Run this when you add a new top-level internal/* package, introduce a new controller package, or change the boundary policy itself.

Decision matrix

Observability and testing expectations

Observability and testing expectations.

Area	Repository expectation	Primary entry point
Metrics	Use the openbao_ prefix and stable label sets.	The metrics conventions in the existing controllers plus review.
Logging	Prefer structured, context-rich logging with consistent field names.	[Kubernetes operator patterns](/contribute/standards/kubernetes-patterns).
Testing	Match the verification depth to the change, and update golden files when renderer output changes.	[Testing strategy](/contribute/testing).
CRD evolution	Prefer additive API changes and document migrations when a breaking shape change is unavoidable.	API review plus [Reference](/docs/reference).

Related build-and-change guides

Go style guideOpen the lower-level coding rules for naming, imports, logging, and reconcilers.Generated artifactsUse the generation map when you know a change should have emitted files but are not sure which command owns them.Kubernetes operator patternsReview the controller-specific patterns that keep reconciliation logic idempotent and boundary-aware.