Skip to content

docs: add CLAUDE.md with deploy-flow guidance #255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ecv wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add CLAUDE.md with deploy-flow guidance #255

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# CLAUDE.md

Guidance for working in this repository (datum-cloud/datum). This is a
Kubebuilder-based Go controller-manager for the Datum control plane.

## Common commands

- `make test` — generate manifests/code, fmt, vet, then run tests (uses envtest).
- `make lint` / `make lint-fix` — run golangci-lint.
- `make build` — build the manager binary.
- `make run` — run a controller against the cluster in `~/.kube/config`.
- `make manifests generate` — regenerate CRDs/RBAC/webhooks and deepcopy code
after changing API types; commit the regenerated output.

## Deployment flow (read before assuming a change is "live")

CI (`.github/workflows/build-and-test.yaml`) publishes the
`ghcr.io/datum-cloud/datum-kustomize` bundle and the `datum` image on every push
(main builds tagged `v0.0.0-main-*`) and on each release tag (`vX.Y.Z`).
Deployment to clusters is driven by Flux in the `datum-cloud/infra` repo:

- **Merging a PR to `main` ships to STAGING only.** The staging OCIRepository
tracks `-main-*` prerelease builds and auto-rolls every main build. Merging is
safe — it does not touch prod.
- **Cutting a release tag (`vX.Y.Z`) auto-ships to PROD.** The prod image policy
matches release semver tags (`>= 0.0.0`); Flux's image-updater then commits the
bump to infra `main`, which the prod cluster tracks and reconciles in ~1–2 min.
There is no further human gate after the tag. **Treat creating a release tag as
the production deploy action**, not merging.

To check the live prod version, read the `datum-kustomize-bundles` OCIRepository
`tag:` in the `datum-system` namespace (or the `$imagepolicy` marker line in
infra's `apps/datum-control-plane-system/core-control-plane/production/datum-oci-repository-patch.yaml`).

## Conventions

- After changing kubebuilder markers (RBAC, webhooks) or generated types, run
`make manifests generate` and commit the regenerated artifacts. Controllers
live in `internal/controller`; API types are largely external (see `PROJECT`).