Skip to content

AGENTS.md

Latest commit

 

History

History
56 lines (45 loc) · 2.89 KB

AGENTS.md

File metadata and controls

56 lines (45 loc) · 2.89 KB
Raw

AGENTS.md

Conventions for AI coding assistants (and humans) working in this repo. Read this before changing anything under charts/.

What this repo is

A collection of reusable Helm charts published to a GitHub Pages Helm repo. The flagship chart is charts/app-chart: a values-driven, generic chart with one template per Kubernetes kind. It has no service-specific logic — a service is described entirely in a values file.

Golden rules (do not violate)

  1. Verbatim splice. Each template renders one Kubernetes kind and splices the object's spec/data straight from values with toYaml. Do not add service-specific branching, hardcoded names, or business logic to templates.
  2. Off by default. Every object renders only when its entry sets enabled: true. A default helm template with no values must render zero objects. Preserve this guard ({{- if not $obj.enabled }}{{- continue }}{{- end }}).
  3. No opinionated defaults in templates. Templates must be deterministic passthroughs: the same values always render the same manifests, and the chart never injects labels, annotations, or defaults of its own. Best practices (recommended labels, securityContext, probes, resource limits) belong in each app's values, not the templates. The unit tests assert exact output to enforce this determinism — if a test breaks, the render changed; understand why before "fixing" the test.
  4. Never hand-edit generated files. charts/*/README.md is generated by helm-docs. Edit values.yaml comments and README.md.gotmpl, then run make docs. Never edit the generated README.md directly.

Before you commit

  • Run make pre-commit (format, helm lint, helm-docs, unittest) until green.
  • Run make unittest, make lint, make kubeconform for the checks CI runs.
  • Bump the chart version in the relevant Chart.yaml — a version is published once and never overwritten, so an un-bumped change never ships.
  • Use Conventional Commit messages (feat: / fix: / chore: …). The type drives the published version bump and is enforced in CI.

Adding functionality

  • Prefer extending an existing kind's values shape over adding logic.
  • Need an arbitrary object the chart doesn't model? Use extraObjects in values — don't add a bespoke template.
  • Do not create a new service-specific chart to work around app-chart. See docs/chart-authoring.md for when a genuinely new chart is warranted.

Where things live

  • charts/app-chart/templates/ — one template per Kubernetes kind.
  • charts/app-chart/values.yaml — documented; every object off by default.
  • charts/app-chart/tests/ — helm-unittest suites (assert exact rendered output).
  • docs/tooling.md — the full toolchain and what runs when.
  • docs/chart-authoring.md, docs/chart-publishing.md — how to add / publish charts.