|
| 1 | +# Cozystack Review Guidelines |
| 2 | + |
| 3 | +## Project Architecture |
| 4 | + |
| 5 | +Cozystack is a Kubernetes-based PaaS built on Helm umbrella charts and FluxCD. |
| 6 | +Packages live in `packages/{core,system,apps,extra,library,tests}/`. The `library/` group holds reusable helper charts; the `tests/` group exists because library charts are not directly testable. |
| 7 | +Each package wraps one or more upstream Helm charts. |
| 8 | +Go code in `cmd/`, `internal/`, `pkg/` implements Kubernetes controllers and API server. |
| 9 | +Static CRDs are generated by `hack/update-codegen.sh` from types under `api/v1alpha1/`, `api/backups/`, and `api/dashboard/`. |
| 10 | +App Kinds (like `Postgres`, `Kafka`) live in `api/apps/v1alpha1/` but are registered dynamically at runtime from `ApplicationDefinition` resources — they are not static CRDs. |
| 11 | + |
| 12 | +## Vendored Code — Critical Rules |
| 13 | + |
| 14 | +**Never suggest editing files inside any `charts/` directory under `packages/`.** |
| 15 | +Those are upstream Helm charts vendored via `make update` (which runs `helm pull`). |
| 16 | +Any direct edit is overwritten on the next update and provides zero value. |
| 17 | + |
| 18 | +If you find an issue that appears to live in vendored chart code: |
| 19 | + |
| 20 | +- For configuration-level changes: suggest overrides in the package root `values.yaml`. |
| 21 | +- For structural changes: suggest a patch file in `packages/<name>/patches/` applied by the Makefile. |
| 22 | +- For source-code changes in images: suggest a patch in `packages/<name>/images/<name>/patches/`. |
| 23 | +- For true upstream bugs: point to the upstream repository and suggest an upstream issue/PR. |
| 24 | +- Do NOT suggest creating `charts/patches/` — patches never live inside `charts/`. |
| 25 | + |
| 26 | +Similarly, never propose edits to: |
| 27 | + |
| 28 | +- `vendor/` — Go dependencies. Changes go through `go get` and `go mod tidy`. |
| 29 | +- `zz_generated.*.go` — regenerated by `make generate`. |
| 30 | +- `pkg/generated/` — auto-generated Kubernetes client code. |
| 31 | +- Image digest values in `values.yaml` — set by CI via `make image`, not by humans. |
| 32 | +- `go.mod` / `go.sum` by hand — use `go get` and `go mod tidy`. |
| 33 | + |
| 34 | +## Commit and PR Requirements |
| 35 | + |
| 36 | +Each commit must start with a component prefix: `[component] Brief description`. |
| 37 | + |
| 38 | +Valid prefixes: |
| 39 | + |
| 40 | +- System: `[dashboard]`, `[platform]`, `[cilium]`, `[kube-ovn]`, `[linstor]`, `[fluxcd]`, `[cluster-api]` |
| 41 | +- Apps: `[postgres]`, `[mariadb]`, `[redis]`, `[kafka]`, `[clickhouse]`, `[kubernetes]`, `[virtual-machine]` |
| 42 | +- Meta: `[tests]`, `[ci]`, `[docs]`, `[maintenance]` |
| 43 | +- Package-specific: any `[<package-name>]` matching a directory under `packages/` |
| 44 | + |
| 45 | +Each commit must have a `Signed-off-by:` trailer (produced by `git commit --signoff`). |
| 46 | + |
| 47 | +PR body must contain a release note block: |
| 48 | + |
| 49 | +````text |
| 50 | +```release-note |
| 51 | +[component] Human-readable changelog entry |
| 52 | +``` |
| 53 | +```` |
| 54 | + |
| 55 | +Flag any PR whose commits lack the prefix or signoff, or whose body has no release-note block. |
| 56 | + |
| 57 | +## Helm Chart Conventions |
| 58 | + |
| 59 | +Packages follow an umbrella chart pattern: |
| 60 | + |
| 61 | +- `charts/` — vendored upstream, read-only |
| 62 | +- `templates/` — Cozystack-specific extra manifests |
| 63 | +- `values.yaml` — override values for the upstream chart |
| 64 | +- `values.schema.json` — JSON Schema for dashboard UI and input validation |
| 65 | + |
| 66 | +When reviewing `values.schema.json`: |
| 67 | + |
| 68 | +- `make generate` regenerates this file and strips `title`, `description`, and `x-*` custom annotations. Do not suggest adding fields that will be stripped on the next regeneration. |
| 69 | +- Focus on type correctness, `required` fields, `enum` values, and default values. |
| 70 | +- Flag breaking changes: removing a field, changing its type, or narrowing its enum. |
| 71 | + |
| 72 | +## Sensitive Components |
| 73 | + |
| 74 | +**`packages/core/platform/`**: the platform chart that deploys everything. Changes here can require updates to the migration flow — the Helm hook in `packages/core/platform/templates/migration-hook.yaml` and the runner image with scripts in `packages/core/platform/images/migrations/`. Flag any change to this package that lacks a corresponding migration update or an explicit note that backward compatibility is preserved. |
| 75 | + |
| 76 | +**`api/apps/v1alpha1/`**: app CRD Kinds are registered at runtime from `ApplicationDefinition` resources and the matching `values.schema.json`. Suggest changes to the relevant package schema rather than hand-editing generated types. |
| 77 | + |
| 78 | +**RBAC, ServiceAccounts, and SecurityContext**: flag overly broad RBAC (`*` on resources or verbs without justification), missing `securityContext`, containers running as root without an explicit reason, and `hostPath`/`hostNetwork` usage without clear rationale. |
| 79 | + |
| 80 | +## Go Code Standards |
| 81 | + |
| 82 | +- Use controller-runtime patterns for reconcilers. |
| 83 | +- Use structured logging via `logr` — flag `fmt.Print*` and `log.Print*` in controller code. |
| 84 | +- Handle errors explicitly. Discarding meaningful errors with `_` is a bug. |
| 85 | +- Propagate `context.Context` through call chains. Flag `context.Background()` created inside a reconciler or request handler. |
| 86 | +- Prefer `ctrl.Result{RequeueAfter: ...}` over empty requeue for predictable reconciliation loops. |
| 87 | +- Tests live beside the code (`*_test.go`). New behavior without tests is worth flagging. |
| 88 | + |
| 89 | +## What to Review Carefully |
| 90 | + |
| 91 | +- Logic errors, off-by-one bugs, nil dereferences. |
| 92 | +- Missing error handling, especially in reconcilers and API handlers. |
| 93 | +- Helm template correctness: missing `quote`, incorrect indentation, wrong scope in `with`/`range`. |
| 94 | +- Security: permissive RBAC, privileged containers, secrets in environment variables, hardcoded credentials. |
| 95 | +- Missing resource requests/limits on new workloads. |
| 96 | +- Breaking changes in `values.schema.json`: removed fields, tightened types, narrower enums. |
| 97 | + |
| 98 | +## Anti-patterns — Do Not Flag These |
| 99 | + |
| 100 | +- Large JSON files in `dashboards/` — imported from upstream Grafana sources, not hand-written. |
| 101 | +- Files under any `charts/` directory — vendored upstream, left as-is intentionally. |
| 102 | +- Whitespace or formatting in `*.patch` / `*.diff` files — machine-applied, not authored. |
| 103 | +- Missing comments on generated code. |
| 104 | +- `go.sum` changes accompanying `go.mod` changes — expected and correct. |
| 105 | +- Fork relationships for vendored tooling images — intentional (e.g., `cozystack/kilo` fork is expected). |
| 106 | +- Absence of unit tests for vendored chart overrides — covered by E2E tests in `hack/e2e-apps/`. |
0 commit comments