You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by vi...@apache.org on 2026/10/17 03:12:40 UTC
(superset-kubernetes-operator) branch main updated: docs(contributing): refresh stale development docs (#451)
This is an automated email from the ASF dual-hosted git repository.
villebro pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/superset-kubernetes-operator.git
The following commit(s) were added to refs/heads/main by this push:
new d119eb3 docs(contributing): refresh stale development docs (#451)
d119eb3 is described below
commit d119eb3ddca2f321473bd1d69b5c3d9c006b587e
Author: Younsung Lee <cy...@kakao.com>
AuthorDate: Sat Oct 17 12:12:34 2026 +0900
docs(contributing): refresh stale development docs (#451)
---
AGENTS.md | 2 +-
docs/contributing/development-guidelines.md | 19 ++++++++++---------
docs/contributing/development-setup.md | 2 +-
docs/contributing/releasing.md | 4 ++--
renovate.json | 16 ++++++++++++++--
5 files changed, 28 insertions(+), 15 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index f5f503e..3d1718f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,7 +21,7 @@ under the License.
## Project Overview
-Kubernetes operator for Apache Superset, built with the Go-based Operator SDK and Go 1.26+.
+Kubernetes operator for Apache Superset, built with the Go-based Operator SDK and Go 1.27.2.
- Module: `github.com/apache/superset-kubernetes-operator`
- API group: `superset.apache.org/v1alpha1`
diff --git a/docs/contributing/development-guidelines.md b/docs/contributing/development-guidelines.md
index aade35f..dccd886 100644
--- a/docs/contributing/development-guidelines.md
+++ b/docs/contributing/development-guidelines.md
@@ -28,7 +28,7 @@ See [Architecture](../architecture/overview.md) for the structural overview (CRD
- **Single public CRD**: `Superset` resolves shared spec (top-level + per-component) into parent-owned Kubernetes resources
- **6 deployment components + lifecycle tasks**: web server, Celery worker, Celery beat, Flower, websocket, MCP, and task Jobs for seed/migrate/rotate/init
-- **3 pure Go packages**: `internal/resolution/` (spec flattening), `internal/config/` (Python rendering), `internal/common/` (shared types)
+- **Pure Go packages** (no controller-runtime dependency): `internal/resolution/` (spec flattening), `internal/config/` (Python rendering), `internal/common/` (shared types), `internal/schedule/` (cron tick computation)
- **Parent resolves and executes**: All layering, lifecycle orchestration, resource reconciliation, and status projection live in the parent controller
### External connection values
@@ -120,11 +120,11 @@ We use a **pyramid testing strategy** where the vast majority of logic is covere
make test-e2e
```
-The Kind node image is pinned in the Makefile (`KIND_NODE_IMAGE`) and matches the Kind binary version used in CI. Override `E2E_PROJECT_IMAGE` or `E2E_CURL_IMAGE` if your environment requires a mirror registry, or set `E2E_SKIP_BUILD_LOAD=1` to reuse an image you've already loaded into Kind during iteration.
+The Kind node image (`KIND_NODE_IMAGE`) is read from the first entry in `.github/supported-k8s.json` and matches the Kind binary version used in CI. Override `E2E_PROJECT_IMAGE` or `E2E_CURL_IMAGE` if your environment requires a mirror registry, or set `E2E_SKIP_BUILD_LOAD=1` to reuse an image you've already loaded into Kind during iteration.
### Writing a new unit test
-Use the standard pattern from `superset_controller_test.go`:
+Use the standard pattern from `reconcile_parent_resources_test.go`:
```go
func TestReconcile_MyScenario(t *testing.T) {
@@ -150,7 +150,7 @@ func TestReconcile_MyScenario(t *testing.T) {
Build()
r := &SupersetReconciler{
- Client: c, Scheme: scheme, Recorder: record.NewFakeRecorder(10),
+ Client: c, Scheme: scheme, Recorder: events.NewFakeRecorder(10),
}
_, err := r.Reconcile(context.Background(), reconcile.Request{
@@ -240,7 +240,7 @@ To check locally (requires Java):
make check-license
```
-The script downloads the Rat jar to `/tmp/lib/` on first run. Files that are generated, scaffolded by Operator SDK, or not user-authored are excluded via `.rat-excludes`.
+The script downloads the Rat jar to `${XDG_CACHE_HOME:-$HOME/.cache}/superset-kubernetes-operator/lib/` on first run. Files that are generated, scaffolded by Operator SDK, or not user-authored are excluded via `.rat-excludes`.
When adding new source files (`.go`, `.yaml`, `.sh`, `Dockerfile`, etc.), include the appropriate license header. Go files get this automatically from `hack/boilerplate.go.txt` when using `make generate`. For other file types, use the `#`-comment form:
@@ -299,7 +299,7 @@ New Deployment/Pod/Container fields go into the template hierarchy:
1. Determine the Kubernetes level: `DeploymentTemplate` (Deployment-level), `PodTemplate` (PodSpec-level), or `ContainerTemplate` (Container-level)
2. Add the field to the appropriate template type in `api/v1alpha1/shared_types.go`
-3. Add the merge logic in `internal/resolution/merge.go` (`MergeDeploymentTemplate`, `MergePodTemplate`, or `MergeContainerTemplate`) using the field's natural semantics (scalar → `ResolveOverridableValue`, named slice → `Merge*ByName`, map → `MergeMaps`, unnamed slice → `append`). All merge functions follow the convention `Merge*(topLevel, component[, operatorInjected])`: the top-level value establishes ordering, the component value overrides by name in place, and where applicable (env [...]
+3. Add the merge logic in `internal/resolution/merge.go` using the field's natural semantics: scalars are overridden by the component value, named collections merge by name, maps merge by key, and unnamed collections append. Values are applied in order: the top-level value establishes ordering, the component value overrides in place, and where applicable (env vars, volume mounts, labels) operator-injected values are applied last so they cannot be overridden by user configuration. Any cod [...]
4. Wire the field in `internal/controller/deployment_builder.go` (`buildDeploymentSpec`)
5. Run `make manifests generate`
6. Add assertions to existing comprehensive tests
@@ -308,9 +308,9 @@ New Deployment/Pod/Container fields go into the template hierarchy:
## How to Add a New Component
1. Add the component spec to the parent `SupersetSpec` in `superset_types.go`.
-2. Add resource defaults in `internal/controller/component_resources.go` via `ComponentResourceDefs()` with component name, `DeploymentConfig` (container name, default command, ports), `hasConfig`, and `hasScaling`.
+2. Add resource defaults in `internal/controller/component_resources.go` via `ComponentResourceDefs()` with component name, `DeploymentConfig` (container name, default command, ports, probes), `defaultPort`, and `hasScaling`.
3. Register the component in `internal/controller/component_descriptors.go`:
- - Add a `componentDescriptor` entry with `extract`, optional `adjustSpec`,
+ - Add a `componentDescriptor` entry with `hasPythonConfig`, `extract`, optional `adjustSpec`,
and `statusAccessor` functions.
- Add the descriptor to the `componentDescriptors` slice.
4. Add status fields if the component needs a dedicated slot under `ComponentStatusMap`.
@@ -328,6 +328,7 @@ internal/
│ # Per-component rendering, metastore URI,
│ # config appending
├── common/ # Shared types (ComponentType, environment constants)
+├── schedule/ # Pure Go — cron tick computation
└── controller/ # controller-runtime — reconcilers
# Parent controller, component resources,
# task job lifecycle, status, scaling, networking
@@ -340,7 +341,7 @@ internal/
| File | Purpose |
|------|---------|
| `api/v1alpha1/shared_types.go` | ImageSpec, MetastoreSpec, DeploymentTemplate, PodTemplate, ContainerTemplate, FlatComponentSpec |
-| `api/v1alpha1/superset_types.go` | Parent SupersetSpec, component specs, InitSpec, CEL validation rules, status |
+| `api/v1alpha1/superset_types.go` | Parent SupersetSpec, component specs, LifecycleSpec, CEL validation rules, status |
| `internal/common/types.go` | Shared ComponentType, environment constants |
| `internal/resolution/resolver.go` | ResolveComponentSpec — core flattening engine |
| `internal/config/renderer.go` | RenderConfig — per-component Python generation |
diff --git a/docs/contributing/development-setup.md b/docs/contributing/development-setup.md
index 3ff2e7d..1b87841 100644
--- a/docs/contributing/development-setup.md
+++ b/docs/contributing/development-setup.md
@@ -28,7 +28,7 @@ This guide walks through setting up a local development environment with Kind, P
| Docker daemon | 20+ | [Docker Desktop](https://docs.docker.com/get-docker/), [Colima](https://github.com/abiosoft/colima) (`brew install colima`), or [Podman](https://podman.io) |
| kubectl | 1.27+ | [kubernetes.io](https://kubernetes.io/docs/tasks/tools/) |
| Kind | 0.30+ | `brew install kind` or `go install sigs.k8s.io/kind@latest` |
-| Go | 1.26+ | `brew install go` or [go.dev](https://go.dev/dl/) |
+| Go | 1.27.2 | `brew install go` or [go.dev](https://go.dev/dl/) |
| Helm | 4+ | `brew install helm` or [helm.sh](https://helm.sh/docs/intro/install/) — used by `make lint` (Helm chart lint) and the chart tests |
### macOS notes
diff --git a/docs/contributing/releasing.md b/docs/contributing/releasing.md
index b9f3f62..64b54bf 100644
--- a/docs/contributing/releasing.md
+++ b/docs/contributing/releasing.md
@@ -31,7 +31,7 @@ Pin all `uses:` references by **full commit SHA**, not version tag. Add a versio
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
```
-**Why**: Version tags are mutable — a compromised upstream can retag a malicious commit to an existing version. SHA pinning makes the reference immutable. Dependabot automatically proposes SHA updates when new versions are released, so maintenance overhead is minimal.
+**Why**: Version tags are mutable — a compromised upstream can retag a malicious commit to an existing version. SHA pinning makes the reference immutable. Renovate automatically proposes SHA updates when new versions are released, so maintenance overhead is minimal.
### Tool binary pinning
@@ -55,7 +55,7 @@ Only add broader permissions when needed (e.g., `packages: write` for image publ
### Renovate
-`renovate.json` is configured to propose weekly dependency updates for Go modules and GitHub Actions. A **7-day minimum release age** is enforced — Renovate will not propose a version until it has been published for at least 7 days. This reduces the risk of adopting a compromised release before the community detects it. Review and merge these PRs promptly to stay current on security patches.
+`renovate.json` is configured to propose dependency updates for Go modules and GitHub Actions. A **7-day minimum release age** is enforced — Renovate will not propose a version until it has been published for at least 7 days. This reduces the risk of adopting a compromised release before the community detects it. Review and merge these PRs promptly to stay current on security patches.
---
diff --git a/renovate.json b/renovate.json
index 890f962..289b6b0 100644
--- a/renovate.json
+++ b/renovate.json
@@ -46,9 +46,9 @@
"enabled": false
},
{
- "description": "The custom go.mod Go directive tracker uses the Docker datasource only for tag availability. Do not try to add Docker digests to go.mod.",
+ "description": "The Go version trackers for go.mod and the docs that mirror it use the Docker datasource only for tag availability. Do not try to add Docker digests to these files.",
"matchManagers": ["custom.regex"],
- "matchFileNames": ["go.mod"],
+ "matchFileNames": ["go.mod", "AGENTS.md", "docs/contributing/development-setup.md"],
"matchDepNames": ["golang"],
"pinDigests": false
},
@@ -124,6 +124,18 @@
"datasourceTemplate": "docker",
"versioningTemplate": "docker"
},
+ {
+ "customType": "regex",
+ "description": "Keep the Go version stated in AGENTS.md and the development setup docs in step with go.mod.",
+ "managerFilePatterns": ["/^AGENTS\\.md$/", "/^docs\\/contributing\\/development-setup\\.md$/"],
+ "matchStrings": [
+ "Operator SDK and Go (?<currentValue>\\d+\\.\\d+\\.\\d+)\\.",
+ "\\| Go \\| (?<currentValue>\\d+\\.\\d+\\.\\d+) \\|"
+ ],
+ "depNameTemplate": "golang",
+ "datasourceTemplate": "docker",
+ "versioningTemplate": "docker"
+ },
{
"customType": "regex",
"description": "Track sigs.k8s.io/kind release pin in supported-k8s.json",