Skip to content

Engineering guidelines

Operator how well — error handling, robustness, security behaviour, and definition of done. Product NFR IDs live in NON_FUNCTIONAL_REQUIREMENTS.md.

Error taxonomy

MQ and network failures are classified per ADR-0014:

Class Behaviour Example
Transient Requeue with backoff; no terminal condition mqweb 5xx, connection reset
Terminal Set Ready=False with clear message; no hot loop Auth failure, invalid MQSC
Configuration Surface in status; user must fix spec/Secret Missing Secret, bad endpoint

Never log credentials or full mqweb bodies at default log levels (NFR SEC-5).

TLS and credentials

  • All mqweb traffic is HTTPS with certificate verification on by default (NFR SEC-2).
  • Custom CA material comes from a referenced Secret (caSecretRef).
  • insecureSkipVerify is opt-in, annotation-guarded, dev-only — never default in samples for production paths.
  • Credentials live in Kubernetes Secrets referenced by QueueManagerConnection only (NFR SEC-1).

Reconciliation robustness

  • Reconcilers are idempotent (NFR REL-1): repeated passes converge; no side effects from duplicate work.
  • Finalizers delete MQ objects before CR removal (ADR-0013).
  • Drift policy for queues/topics/channels uses DISPLAY vs DEFINE matrices (ATTRIBUTE_RECONCILIATION.md).
  • Periodic requeue is a backstop for mqweb freshness; watch-driven triggers (CR, QMC, referenced Secrets) are primary.

Webhook availability

Validating admission uses failurePolicy: Fail (ADR-0009). Stateless rules should migrate to CEL CRD validations over time to shrink the blast radius.

Definition of done

A change is done when:

  1. The right test tier is updated (see testing.md).
  2. Generated artifacts are fresh (task verify).
  3. Lint and format are clean (task lint, task format:check).
  4. Non-obvious decisions have an ADR or update an existing one.
  5. User-facing behaviour is reflected in docs/samples when applicable.
Document Owns
coding-standards.md Go style, lint, CI gates
testing.md Test pyramid and coverage
../CONTRIBUTING.md PR process and DCO
../AGENTS.md AI agent workflow