Conventions¶

This document describes the conventions and practices we follow when working in this repository. Consistency here reduces review friction and keeps the codebase predictable.

Git¶

No Direct Pushes to Main¶

All changes must go through a pull request. Direct pushes to main are not allowed. PRs provide a review checkpoint and a clear history of intent behind each change.

Keep Documentation Up to Date¶

When introducing a new feature or modifying existing behaviour, update the relevant documentation in the same PR. Documentation in docs/content/ is part of the change — not a follow-up task.

Kubernetes Manifests¶

Name Files After Their Kind¶

Manifest files are named after the Kubernetes kind they contain, in lowercase kebab-case:

deployment.yaml
service.yaml
httproute.yaml
cluster-secret-store.yaml
cluster-external-secret.yaml

Group Same-Kind Manifests in One File¶

If a directory contains multiple manifests of the same kind, they belong in a single file separated by ---. Do not create separate files per instance.

# cluster-role-binding.yaml
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: foo
...
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: bar
...

Cluster-Specific Values Belong at the Cluster Level¶

If a value in a manifest is specific to a cluster (hostname, IP, replica count, credentials path, etc.), it must not be hardcoded in components/. It either:

• Gets injected via variable substitution from the cluster-config ConfigMap, or
• Gets applied as a patch in cluster/<name>/

The component layer defines structure and defaults. The cluster layer defines specifics. See Repository Structure for how this works in practice.