From 9248934fb74e27ce3b096edcfa4eb9f4399e046b Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 4 Jun 2026 14:46:23 +0300 Subject: [PATCH 01/11] Adding AGENTS.md Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 --- AGENTS.md | 292 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..171b252e0c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,292 @@ +# Cloud Agent Instructions for kpt + +For Copilot, Cursor, Codex, Gemini Code Assist or any agents generating code or review Pull Requests +in this repository. + +## Generic rules + +### Coding + +* Never commit directly to this repository, always aim for a pull request +* Always ask for a final review of a human before commiting +* Make sure that AI agent usage is attributed in the correct way + +### Reviewing PRs + +* When comitting suggested changes add a signoff of the approving human and add the `Assisted-by` + tag to the commit message +* If a comment was not accepted and the Conversation was resolved do not make the same comment again + + +## Repository Overview + +**kpt** is a package-centric toolchain that automates Kubernetes configuration editing and management. It enables declarative configuration authoring, automation, and delivery at scale through a "Configuration as Data" approach, supporting Kubernetes platforms and KRM-driven infrastructure (e.g., Config Connector, Crossplane). + +- **Language**: Go 1.26.3 +- **Repository Size**: ~78 MB +- **License**: Apache 2.0 +- **Key Topics**: Kubernetes, configuration management, CLI tooling, GitOps, policy-as-code, KRM (Kubernetes Resource Model) + +## Quick Build & Test Commands + +**Trust these instructions first.** Only perform searches if you find this information incomplete or inaccurate. + +### Prerequisites +- Go 1.26.3 (specified in `go.mod`) +- Git (required and checked at runtime) +- Docker or Podman (for `test-docker` and function runtime tests) +- Kind v0.30.0 (for e2e live apply tests with Kubernetes 1.33 and 1.34) + +### Build + +```bash +make build +``` +This compiles kpt to `$(go env GOPATH)/bin/kpt` using LDFLAGS with git commit SHA. + +### Run All Checks (Build, Test, Lint) + +```bash +make all +``` + +Runs: `fix vet fmt lint test build tidy` in sequence. *Always* run this before committing. + +### Unit Tests + +```bash +make test +``` + +Runs Go tests with coverage. Set `KRM_FN_RUNTIME` to select function runtime (docker/podman, default uses system default). + +### Docker/Podman Runtime Tests + +```bash +make test-docker +``` + +Requires Docker or Podman. Tests that need container runtime (e.g., pipeline tests). Respects `KRM_FN_RUNTIME` environment variable. + +### E2E Function Tests + +#### Render tests + +```bash +make make test-fn-render T=".*" +``` +#### Eval tests + +```bash +make make test-fn-eval T=".*" +``` + +Use `T` parameter to filter tests by regex (e.g., `T=fnconfig` for function config tests). Set `KRM_FN_RUNTIME` to select runtime. + +### E2E Live Apply Tests + +```bash +make test-live-apply +``` + +Requires KinD with Kubernetes 1.33.4 and 1.34.0 (specific SHAs pinned in CI). These tests use Kind internally. Timeout is 20 minutes. + +### Linting + +```bash +make lint +``` + +Runs golangci-lint v2.11.4. If already installed locally with matching version, uses it; otherwise downloads and runs via `go run`. + +### Code Generation & Formatting + +```bash +make fmt # Run gofmt and goimports +make fix # Run go fix +make vet # Run go vet +make tidy # Run go mod tidy +make generate # Generate code from templates (mdtogo, copyright headers) +make schema # Generate schema +``` + +### Setting Up Git Config (Required for Tests) + +Many tests require git configuration: + +```bash +git config --global user.email "you@example.com" +git config --global user.name "Your Name" +``` + +## Project Layout + +### Root Level Files & Directories + +* **main.go**: CLI entry point; contains //go:generate directives for CLI documentation +* **Makefile**: Primary build orchestration +* **.golangci.yml**: Linting configuration (golangci-lint v2.11.4) +* **go.mod / go.sum**: Dependency management (Go 1.26.3) +* **CONTRIBUTING.md**: Contribution guidelines and code review requirements +* **CODEOWNERS**: Default reviewers + +### Key Source Directories + +* **cmd/**: CLI command implementations using Cobra framework +* **run/**: Main CLI setup; contains GetMain() that initializes Cobra commands with environment setup +* **pkg/**: Core library packages (business logic, utilities) +* **internal/**: Internal packages; includes internal/docs/generated/ (generated from Markdown via mdtogo) +* **mdtogo/**: Code generator tool that converts CLI documentation Markdown files to Go variables + +### Build & CI Configuration + +* **.github/workflows/go.yml**: Main CI workflow + * Runs on Linux (docker/podman matrix) and macOS + * Executes: `make all` + `make test-docker` + * Triggered on PRs and pushes (excludes dependabot branches) +* **.github/workflows/verifyContent.yml**: Verifies CLI examples + * Runs `make build`, installs mdrip/kind, runs `make site-verify-examples` + * Triggered on changes to `commands/`, `internal/` paths +* **.github/workflows/e2eEnvironment.yml**: KinD-based e2e tests + * Tests Kubernetes 1.33 and 1.34 with KinD v0.30.0 + * Runs `./e2e/live/end-to-end-test.sh -k ` +* **.github/workflows/live-e2e.yml**: Live apply e2e tests + * Tests with pinned Kubernetes image SHAs + * Runs `make test-live-apply` with `K8S_VERSION` environment variable + +### Documentation & Tests + +* **documentation/**: Hugo-based website published to kpt.dev + * Run `make serve` from root (serves docs locally) + * Requires `npm install` first + +* **e2e/**: End-to-end test suites + * Contains testdata directories for function render/eval tests + * Live tests in `e2e/live/end-to-end-test.sh` + +### Other Notable Directories + +* **release/**: Release automation (GoReleaser config, Homebrew formula generation) +* **hack/**: Miscellaneous development utilities +* **healthcheck/**: Separate module for health checking (Go 1.26.3, local Makefile) +* **thirdparty/**: Third-party code (excluded from linting) +* **Formula/**: Homebrew package definition (generated by `go run ./release/formula/main.go VERSION`) + +## Linting Rules & Style + +### Linter Configuration + +* **Enabled Linters**: bodyclose, copyloopvar, dogsled, dupl, errcheck, gochecknoinits, goconst, gocritic, gocyclo, govet, ineffassign, lll, misspell, nakedret, revive, staticcheck, unconvert, unparam, unused, whitespace +* **Duplication Threshold**: 400 lines +* **Cyclomatic Complexity**: max 30 +* **Line Length**: max 170 characters +* **Revive Confidence**: 0.85 +* **Excluded Paths**: thirdparty/, third_party, builtin, examples +* **Test Files**: Further relaxed rules (gosec, funlen disabled for *_test.go files) + +### Code Style Requirements (from CONTRIBUTING.md) + +* **Copyright Headers**: All files must have Apache 2.0 license header + * Use format: // Copyright YEAR The kpt Authors (or year range if modified) + * Year should match creation year, or creation-to-modification year range +* **Developer Certificate of Origin (DCO)**: Commits must be signed with -s flag +* **Large Features**: Require reviewed and merged design document (use /docs/design-docs/00-template.md as template) +* **AI Usage**: Must declare AI usage in PR description and commit messages with `Assisted-by: AGENT_NAME:MODEL_VERSION` format + +## Validation Checklist for PRs + +Before submitting a PR, verify: + +1. ✅ All tests pass: make all +1. ✅ All linting passes: make lint +1. ✅ Code formatted: make fmt +1. ✅ Dependencies tidied: make tidy +1. ✅ Copyright headers added/updated per CONTRIBUTING.md +1. ✅ DCO sign-off: use git commit -s +1. ✅ For CLI/API changes: design document reviewed and merged +1. ✅ AI usage declared in PR description (if applicable) + +## Common Build Issues & Workarounds + +### Docker/Podman Not Available + +If `make test-docker` fails due to missing Docker/Podman: + +* Install Docker Desktop or Podman +* For Podman: ensure it's on PATH and `podman version` runs successfully +* Set `KRM_FN_RUNTIME=podman` if using Podman + +### KinD Setup Issues + +For e2e live tests (`make test-live-apply`): + +* KinD v0.30.0 is auto-installed by CI workflow +* Requires Docker running in background +* Tests use specific Kubernetes image SHAs (see live-e2e.yml matrix) +* Timeout is 20 minutes; allow sufficient time + +### Git Configuration + +Tests fail silently if git user not configured. Always run: + +```bash +git config --global user.email "you@example.com" +git config --global user.name "Your Name" +``` + +### Module Generation + +If changes modify CLI documentation in documentation/content/en/reference/cli/: + +* Run `make generate` to regenerate `internal/docs/generated/` +* Commit generated files + +### Known CI Skips + +* Windows build currently disabled (see `.github/workflows/go.yml` line 88-104, issue #3463) +* Some linters disabled: `funlen`, `gosec` (marked TODO in .`golangci.yml`) + +## Environment Variables + +* **KRM_FN_RUNTIME**: Select function runtime for tests: `docker`, `podman` or `nerdctl` +* **K8S_VERSION**: Kubernetes version for e2e live tests (used in CI with pinned SHAs) +* **KPT_NO_PAGER_HELP**: Set to 1 to disable pager for help output +PAGER: Custom pager command (default: less -R) +* **KPT_FN_WASM_RUNTIME**: WASM function runtime selection +* **GOPATH**: Go workspace path (used in CI workflows) +* **GOBIN**: Go binary installation directory + +## Key Dependencies + +* **Cobra**: CLI framework +* **Kubernetes libraries (k8s.io/*)**: For Kubernetes resource handling +* **sigs.k8s.io/cli-utils**: CLI utilities +* **sigs.k8s.io/kustomize/kyaml**: YAML handling for Kubernetes +* **sigs.k8s.io/controller-runtime**: Controller and reconciliation patterns +* **wasmtime-go**: WebAssembly function runtime +* **go-containerregistry**: Container image handling + +## Testing Strategy + +* **Unit Tests**: Run with `make test` (standard Go tests) +* **Docker-based Tests**: Run with `make test-docker` (requires container runtime) +* **Function E2E Tests**: Run with make `test-fn-render` / `make test-fn-eval` (testdata-driven) +* **Live Apply E2E**: Run with `make test-live-apply` (KinD-based, 20-minute timeout) +* **Example Verification**: Run with `make site-verify-examples` (verifies CLI examples in docs) + +## Implementation Notes for Code Changes + +* **CLI Commands**: Add to `commands/` directory; use Cobra; update `documentation/cli` for documentation +* **Library Code**: Place in `pkg/` for public APIs; use `internal/` for internal utilities +* **Tests**: Colocate `*_test.go` files with source; use testdata directories for fixtures +* **Generated Code**: Run `make generate` after modifying templates +* **Linting Issues**: Address all `golangci-lint` findings; consult `.golangci.yml` for thresholds +* **Git Flow**: Always create feature branches; use squash-merge preferred per repository settings +* **Documentation**: Update Markdown in documentation/; run `make serve` to make sure that there are no errors + +Trust these instructions. They have been validated against the Makefile, GitHub workflows, go.mod, +and contributing guidelines. Only search for additional details if: + +* Build or test commands fail with unexpected errors +* Instructions reference non-existent paths or commands +* New tool versions are released and compatibility is unclear From 18dc440f493551c104458afa0cab83edbf9ec341 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 4 Jun 2026 15:58:06 +0300 Subject: [PATCH 02/11] Apply suggestions from code review Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 171b252e0c..289089526c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ in this repository. ### Coding * Never commit directly to this repository, always aim for a pull request -* Always ask for a final review of a human before commiting +* Always ask for a final review from a human before committing * Make sure that AI agent usage is attributed in the correct way ### Reviewing PRs @@ -35,7 +35,7 @@ in this repository. - Go 1.26.3 (specified in `go.mod`) - Git (required and checked at runtime) - Docker or Podman (for `test-docker` and function runtime tests) -- Kind v0.30.0 (for e2e live apply tests with Kubernetes 1.33 and 1.34) +- KinD (CI uses v0.30.0; `make install-kind` installs v0.29.0) (for e2e live apply tests with Kubernetes 1.33 and 1.34) ### Build @@ -73,12 +73,12 @@ Requires Docker or Podman. Tests that need container runtime (e.g., pipeline tes #### Render tests ```bash -make make test-fn-render T=".*" +make test-fn-render T=".*" ``` #### Eval tests ```bash -make make test-fn-eval T=".*" +make test-fn-eval T=".*" ``` Use `T` parameter to filter tests by regex (e.g., `T=fnconfig` for function config tests). Set `KRM_FN_RUNTIME` to select runtime. @@ -132,7 +132,7 @@ git config --global user.name "Your Name" ### Key Source Directories -* **cmd/**: CLI command implementations using Cobra framework +* **commands/**: CLI command implementations using Cobra framework * **run/**: Main CLI setup; contains GetMain() that initializes Cobra commands with environment setup * **pkg/**: Core library packages (business logic, utilities) * **internal/**: Internal packages; includes internal/docs/generated/ (generated from Markdown via mdtogo) @@ -244,7 +244,7 @@ If changes modify CLI documentation in documentation/content/en/reference/cli/: ### Known CI Skips * Windows build currently disabled (see `.github/workflows/go.yml` line 88-104, issue #3463) -* Some linters disabled: `funlen`, `gosec` (marked TODO in .`golangci.yml`) +* Some linters disabled: `funlen`, `gosec` (marked TODO in `.golangci.yml`) ## Environment Variables From 6ca098209d4cd60f59bc637e8635e4b8a4a233bc Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 5 Jun 2026 09:15:34 +0300 Subject: [PATCH 03/11] Apply suggestions from code review Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 289089526c..508d837c93 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,6 @@ # Cloud Agent Instructions for kpt -For Copilot, Cursor, Codex, Gemini Code Assist or any agents generating code or review Pull Requests -in this repository. +For Copilot, Cursor, Codex, Gemini Code Assist, or any agents generating code or reviewing pull requests in this repository. ## Generic rules @@ -13,8 +12,7 @@ in this repository. ### Reviewing PRs -* When comitting suggested changes add a signoff of the approving human and add the `Assisted-by` - tag to the commit message +* When committing suggested changes, add a sign-off from the approving human and add the `Assisted-by` tag to the commit message * If a comment was not accepted and the Conversation was resolved do not make the same comment again @@ -157,8 +155,8 @@ git config --global user.name "Your Name" ### Documentation & Tests * **documentation/**: Hugo-based website published to kpt.dev - * Run `make serve` from root (serves docs locally) - * Requires `npm install` first + * Run `make serve` from `documentation/` (serves docs locally) + * Requires `npm install` first (run in `documentation/`) * **e2e/**: End-to-end test suites * Contains testdata directories for function render/eval tests @@ -251,7 +249,7 @@ If changes modify CLI documentation in documentation/content/en/reference/cli/: * **KRM_FN_RUNTIME**: Select function runtime for tests: `docker`, `podman` or `nerdctl` * **K8S_VERSION**: Kubernetes version for e2e live tests (used in CI with pinned SHAs) * **KPT_NO_PAGER_HELP**: Set to 1 to disable pager for help output -PAGER: Custom pager command (default: less -R) +* **PAGER**: Custom pager command (default: less -R) * **KPT_FN_WASM_RUNTIME**: WASM function runtime selection * **GOPATH**: Go workspace path (used in CI workflows) * **GOBIN**: Go binary installation directory @@ -270,13 +268,13 @@ PAGER: Custom pager command (default: less -R) * **Unit Tests**: Run with `make test` (standard Go tests) * **Docker-based Tests**: Run with `make test-docker` (requires container runtime) -* **Function E2E Tests**: Run with make `test-fn-render` / `make test-fn-eval` (testdata-driven) +* **Function E2E Tests**: Run with `make test-fn-render` / `make test-fn-eval` (testdata-driven) * **Live Apply E2E**: Run with `make test-live-apply` (KinD-based, 20-minute timeout) * **Example Verification**: Run with `make site-verify-examples` (verifies CLI examples in docs) ## Implementation Notes for Code Changes -* **CLI Commands**: Add to `commands/` directory; use Cobra; update `documentation/cli` for documentation +* **CLI Commands**: Add to `commands/` directory; use Cobra; update `documentation/content/en/reference/cli/` for documentation * **Library Code**: Place in `pkg/` for public APIs; use `internal/` for internal utilities * **Tests**: Colocate `*_test.go` files with source; use testdata directories for fixtures * **Generated Code**: Run `make generate` after modifying templates From fdeaee650aa83db6f2c2f14773ca6cdc9688f260 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 5 Jun 2026 09:24:38 +0300 Subject: [PATCH 04/11] Fixing make fmt target description Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 508d837c93..0c8392254f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,7 +100,7 @@ Runs golangci-lint v2.11.4. If already installed locally with matching version, ### Code Generation & Formatting ```bash -make fmt # Run gofmt and goimports +make fmt # Run gofmt make fix # Run go fix make vet # Run go vet make tidy # Run go mod tidy From a2f8a331e499f819fc1c80fb0fc4f0def6a7be3b Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 5 Jun 2026 10:24:05 +0300 Subject: [PATCH 05/11] Fixes based on Copilot comments Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 --- AGENTS.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0c8392254f..7195841cfc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -141,7 +141,7 @@ git config --global user.name "Your Name" * **.github/workflows/go.yml**: Main CI workflow * Runs on Linux (docker/podman matrix) and macOS * Executes: `make all` + `make test-docker` - * Triggered on PRs and pushes (excludes dependabot branches) + * Triggered on PRs on pushes (pushes exclude dependabot branches) * **.github/workflows/verifyContent.yml**: Verifies CLI examples * Runs `make build`, installs mdrip/kind, runs `make site-verify-examples` * Triggered on changes to `commands/`, `internal/` paths @@ -180,16 +180,18 @@ git config --global user.name "Your Name" * **Line Length**: max 170 characters * **Revive Confidence**: 0.85 * **Excluded Paths**: thirdparty/, third_party, builtin, examples -* **Test Files**: Further relaxed rules (gosec, funlen disabled for *_test.go files) +* **Test Files**: `funlen` and `gosec` are currently disabled project-wide (see `.golangci.yml`); if enabled later, + test files have additional exclusions configured. ### Code Style Requirements (from CONTRIBUTING.md) * **Copyright Headers**: All files must have Apache 2.0 license header * Use format: // Copyright YEAR The kpt Authors (or year range if modified) - * Year should match creation year, or creation-to-modification year range + * Year should match creation year, or creation-to-modification year range * **Developer Certificate of Origin (DCO)**: Commits must be signed with -s flag * **Large Features**: Require reviewed and merged design document (use /docs/design-docs/00-template.md as template) -* **AI Usage**: Must declare AI usage in PR description and commit messages with `Assisted-by: AGENT_NAME:MODEL_VERSION` format +* **AI Usage**: Must declare AI usage in the PR description; `Assisted-by: AGENT_NAME:MODEL_VERSION` attribution in + commit messages is recommended (see CONTRIBUTING.md). ## Validation Checklist for PRs From 6f7c4f62098e2c13327f59e6c2bea0da6176ceaf Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Wed, 10 Jun 2026 10:29:15 +0300 Subject: [PATCH 06/11] Apply suggestions from code review Signed-off-by: Gergely Csatari Assisted-by: GitHub Copilot: Claude Haiku 4.5 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7195841cfc..43db436a53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ For Copilot, Cursor, Codex, Gemini Code Assist, or any agents generating code or - Go 1.26.3 (specified in `go.mod`) - Git (required and checked at runtime) - Docker or Podman (for `test-docker` and function runtime tests) -- KinD (CI uses v0.30.0; `make install-kind` installs v0.29.0) (for e2e live apply tests with Kubernetes 1.33 and 1.34) +- KinD (CI uses v0.30.0 for live e2e/apply workflows; `make install-kind` installs v0.29.0 and is used by `verifyContent.yml`) (for e2e live apply tests with Kubernetes 1.33 and 1.34) ### Build @@ -141,7 +141,7 @@ git config --global user.name "Your Name" * **.github/workflows/go.yml**: Main CI workflow * Runs on Linux (docker/podman matrix) and macOS * Executes: `make all` + `make test-docker` - * Triggered on PRs on pushes (pushes exclude dependabot branches) + * Triggered on PRs (except changes limited to ignored paths like `**.md`) and pushes (pushes exclude dependabot branches) * **.github/workflows/verifyContent.yml**: Verifies CLI examples * Runs `make build`, installs mdrip/kind, runs `make site-verify-examples` * Triggered on changes to `commands/`, `internal/` paths From f1a88ef44b4fd2b9fb14e707658ef9b3cdc6b3ba Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 11 Jun 2026 12:26:01 +0300 Subject: [PATCH 07/11] Removing references to verifyContent.yml workflow Signed-off-by: Gergely Csatari --- AGENTS.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 43db436a53..26d255fc48 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ For Copilot, Cursor, Codex, Gemini Code Assist, or any agents generating code or - Go 1.26.3 (specified in `go.mod`) - Git (required and checked at runtime) - Docker or Podman (for `test-docker` and function runtime tests) -- KinD (CI uses v0.30.0 for live e2e/apply workflows; `make install-kind` installs v0.29.0 and is used by `verifyContent.yml`) (for e2e live apply tests with Kubernetes 1.33 and 1.34) +- KinD (CI uses v0.30.0 for live e2e/apply workflows) (for e2e live apply tests with Kubernetes 1.33 and 1.34) ### Build @@ -142,9 +142,6 @@ git config --global user.name "Your Name" * Runs on Linux (docker/podman matrix) and macOS * Executes: `make all` + `make test-docker` * Triggered on PRs (except changes limited to ignored paths like `**.md`) and pushes (pushes exclude dependabot branches) -* **.github/workflows/verifyContent.yml**: Verifies CLI examples - * Runs `make build`, installs mdrip/kind, runs `make site-verify-examples` - * Triggered on changes to `commands/`, `internal/` paths * **.github/workflows/e2eEnvironment.yml**: KinD-based e2e tests * Tests Kubernetes 1.33 and 1.34 with KinD v0.30.0 * Runs `./e2e/live/end-to-end-test.sh -k ` From e9072e6dc09a42698eb1bd314e643295d9ebb097 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 11 Jun 2026 12:52:04 +0300 Subject: [PATCH 08/11] Corrections based on Laszlo's comments Signed-off-by: Gergely Csatari --- AGENTS.md | 27 +++++++++++---------------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 26d255fc48..fd2e9f0c8b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,8 +20,7 @@ For Copilot, Cursor, Codex, Gemini Code Assist, or any agents generating code or **kpt** is a package-centric toolchain that automates Kubernetes configuration editing and management. It enables declarative configuration authoring, automation, and delivery at scale through a "Configuration as Data" approach, supporting Kubernetes platforms and KRM-driven infrastructure (e.g., Config Connector, Crossplane). -- **Language**: Go 1.26.3 -- **Repository Size**: ~78 MB +- **Language**: Go (version is defined in the [go.mod](./go.mod) file) - **License**: Apache 2.0 - **Key Topics**: Kubernetes, configuration management, CLI tooling, GitOps, policy-as-code, KRM (Kubernetes Resource Model) @@ -30,10 +29,10 @@ For Copilot, Cursor, Codex, Gemini Code Assist, or any agents generating code or **Trust these instructions first.** Only perform searches if you find this information incomplete or inaccurate. ### Prerequisites -- Go 1.26.3 (specified in `go.mod`) +- Go (version is specified in [go.mod](./go.mod)) - Git (required and checked at runtime) - Docker or Podman (for `test-docker` and function runtime tests) -- KinD (CI uses v0.30.0 for live e2e/apply workflows) (for e2e live apply tests with Kubernetes 1.33 and 1.34) +- KinD (CI uses the version defined in `.github/workflows/e2eEnvironment.yml`) ### Build @@ -123,8 +122,8 @@ git config --global user.name "Your Name" * **main.go**: CLI entry point; contains //go:generate directives for CLI documentation * **Makefile**: Primary build orchestration -* **.golangci.yml**: Linting configuration (golangci-lint v2.11.4) -* **go.mod / go.sum**: Dependency management (Go 1.26.3) +* **.golangci.yml**: Linting configuration (used golangci-lint version is defined in the `GOLANGCI_LINT_VERSION` variable of the [Makefile](./Makefile)) +* **go.mod / go.sum**: Dependency management * **CONTRIBUTING.md**: Contribution guidelines and code review requirements * **CODEOWNERS**: Default reviewers @@ -148,6 +147,9 @@ git config --global user.name "Your Name" * **.github/workflows/live-e2e.yml**: Live apply e2e tests * Tests with pinned Kubernetes image SHAs * Runs `make test-live-apply` with `K8S_VERSION` environment variable +* **.github/workflows/release-api.yml**: Release the kpt API module + * Builds, tests and lints the kpt API module + * Runs `make api` ### Documentation & Tests @@ -163,7 +165,7 @@ git config --global user.name "Your Name" * **release/**: Release automation (GoReleaser config, Homebrew formula generation) * **hack/**: Miscellaneous development utilities -* **healthcheck/**: Separate module for health checking (Go 1.26.3, local Makefile) +* **healthcheck/**: Separate module for health checking (Go (Go version is defined in [healthcheck/go.mod](./healthcheck/go.mod)), local Makefile) * **thirdparty/**: Third-party code (excluded from linting) * **Formula/**: Homebrew package definition (generated by `go run ./release/formula/main.go VERSION`) @@ -171,14 +173,7 @@ git config --global user.name "Your Name" ### Linter Configuration -* **Enabled Linters**: bodyclose, copyloopvar, dogsled, dupl, errcheck, gochecknoinits, goconst, gocritic, gocyclo, govet, ineffassign, lll, misspell, nakedret, revive, staticcheck, unconvert, unparam, unused, whitespace -* **Duplication Threshold**: 400 lines -* **Cyclomatic Complexity**: max 30 -* **Line Length**: max 170 characters -* **Revive Confidence**: 0.85 -* **Excluded Paths**: thirdparty/, third_party, builtin, examples -* **Test Files**: `funlen` and `gosec` are currently disabled project-wide (see `.golangci.yml`); if enabled later, - test files have additional exclusions configured. +* Linter configuration is defined in the [.golangci.yml](./.golangci.yml) file ### Code Style Requirements (from CONTRIBUTING.md) @@ -245,7 +240,7 @@ If changes modify CLI documentation in documentation/content/en/reference/cli/: ## Environment Variables -* **KRM_FN_RUNTIME**: Select function runtime for tests: `docker`, `podman` or `nerdctl` +* **KRM_FN_RUNTIME**: Select function runtime for tests: `docker`, `podman` or `nerdctl` * **K8S_VERSION**: Kubernetes version for e2e live tests (used in CI with pinned SHAs) * **KPT_NO_PAGER_HELP**: Set to 1 to disable pager for help output * **PAGER**: Custom pager command (default: less -R) From eb6c0fe5beb1393b4e0a810a50b35bdbbf4d619b Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Tue, 23 Jun 2026 09:15:05 +0300 Subject: [PATCH 09/11] Clarificationon code review commit tagging Signed-off-by: Gergely Csatari --- AGENTS.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fd2e9f0c8b..5e40c1a410 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,13 +12,17 @@ For Copilot, Cursor, Codex, Gemini Code Assist, or any agents generating code or ### Reviewing PRs -* When committing suggested changes, add a sign-off from the approving human and add the `Assisted-by` tag to the commit message +* When committing suggested changes, add a sign-off from the human author and add the `Assisted-by` + tag with the suggesting agent and its used model to the commit message * If a comment was not accepted and the Conversation was resolved do not make the same comment again ## Repository Overview -**kpt** is a package-centric toolchain that automates Kubernetes configuration editing and management. It enables declarative configuration authoring, automation, and delivery at scale through a "Configuration as Data" approach, supporting Kubernetes platforms and KRM-driven infrastructure (e.g., Config Connector, Crossplane). +**kpt** is a package-centric toolchain that automates Kubernetes configuration editing and +management. It enables declarative configuration authoring, automation, and delivery at scale +through a "Configuration as Data" approach, supporting Kubernetes platforms and KRM-driven +infrastructure (e.g., Config Connector, Crossplane). - **Language**: Go (version is defined in the [go.mod](./go.mod) file) - **License**: Apache 2.0 From 1ab0e4a6c6a3bae2a4bfb0ed5b4ee0aaf2d987e6 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 23 Jul 2026 09:45:47 +0300 Subject: [PATCH 10/11] Apply suggestions from code review Signed-off-by: Gergely Csatari Co-authored-by: Aravindhan Ayyanathan --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 5e40c1a410..742741f307 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -239,7 +239,7 @@ If changes modify CLI documentation in documentation/content/en/reference/cli/: ### Known CI Skips -* Windows build currently disabled (see `.github/workflows/go.yml` line 88-104, issue #3463) +* Windows build currently disabled (see `.github/workflows/go.yml`, issue #3463) * Some linters disabled: `funlen`, `gosec` (marked TODO in `.golangci.yml`) ## Environment Variables From 96783d2d015527c5ef5163797c05e97aaa991bbd Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 23 Jul 2026 10:05:57 +0300 Subject: [PATCH 11/11] Fixing review comments and detailing Copilot instructons Signed-off-by: Gergely Csatari --- .github/copilot-code-review.yml | 67 +++++++++++++++++++++++++++++++++ .github/copilot-instructions.md | 3 ++ AGENTS.md | 11 ++++-- 3 files changed, 77 insertions(+), 4 deletions(-) create mode 100644 .github/copilot-code-review.yml create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-code-review.yml b/.github/copilot-code-review.yml new file mode 100644 index 0000000000..ac5dbc50b0 --- /dev/null +++ b/.github/copilot-code-review.yml @@ -0,0 +1,67 @@ +# Copyright 2026 The kpt Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Copilot code review configuration for kpt +# kpt is a Kubernetes configuration package management and orchestration system + +review: + instructions: + # Linter overlap — these are already enforced by golangci-lint in CI + - "Do not comment on issues caught by: errcheck, govet, ineffassign, staticcheck, unused, nosprintfhostport, gofmt" + - "Do not comment on import ordering or formatting" + + # Style — established project conventions + - "Do not comment on error wrapping style (this project uses fmt.Errorf with %w consistently)" + - "Do not suggest renaming variables, functions, or packages unless semantically misleading" + - "Do not suggest extracting single-use helper functions" + - "Do not suggest adding comments to exported symbols unless the function is non-obvious" + + # Architecture context + - "This is a Kubernetes configuration management tool using kyaml/kustomize ecosystem" + - "Controllers and APIs follow kpt's Kptfile specification and package management patterns" + - "Do not flag intentional use of nil results in pkg operations (graceful fallback patterns)" + - "log.FromContext(ctx) is the logging convention — do not suggest alternatives" + - "Testing uses testutil setup patterns with git repositories and workspaces — do not refactor test helpers" + + # What to actually review + - "Focus on: logic errors, race conditions, resource leaks, deadlocks, nil pointer dereferences" + - "Flag: missing context cancellation checks, unbounded goroutines, missing error handling in deferred Close calls" + - "Flag: incorrect kyaml/kustomize API usage, broken file system operations" + - "Flag: security issues (credential leaks, injection vulnerabilities, path traversal)" + - "Flag: incorrect Git/package handling (bad ref handling, missing upstream validation)" + - "Flag: potential issues with YAML/Kptfile parsing or manipulation" + + path_instructions: + - path: "api/generated/**" + instructions: "Do not review — generated by k8s code-generator" + - path: "**/zz_generated*" + instructions: "Do not review — generated by controller-tools" + - path: "third_party/**" + instructions: "Do not review — vendored upstream code" + - path: "go.sum" + instructions: "Do not review" + - path: "go.mod" + instructions: "Only flag if a dependency looks suspicious or has a known CVE" + - path: "docs/**" + instructions: "Only flag factual errors or broken links. Do not comment on grammar or style" + - path: "site/**" + instructions: "Only flag factual errors. Do not suggest style/formatting changes to documentation" + - path: "**/*_test.go" + instructions: "Focus on correctness and flakiness risks. testify (assert/require) and table-driven tests are the standard. Do not suggest style changes or test refactoring" + - path: "test/**" + instructions: "Only flag correctness/security issues. testutil patterns are intentional — do not suggest refactoring. Note: golangci-lint excludes test/ from CI linting" + - path: ".github/**" + instructions: "Focus on security (pinned actions, minimal permissions, injection risks). Do not suggest cosmetic changes" + - path: "examples/**" + instructions: "Only flag correctness issues. These are tutorial configs — do not enforce strict linting" diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..add6654a87 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,3 @@ +# GitHub Copilot Instructions for kpt + +[See AGENTS.md](../AGENTS.md) for information for agents in this project. \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 742741f307..d7b10f308f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,7 +90,9 @@ Use `T` parameter to filter tests by regex (e.g., `T=fnconfig` for function conf make test-live-apply ``` -Requires KinD with Kubernetes 1.33.4 and 1.34.0 (specific SHAs pinned in CI). These tests use Kind internally. Timeout is 20 minutes. +Requires KinD with Kubernetres versions defined in `jobs.kind.strategy.matrix.version` path of the +[e2e test workflows](.github/workflows/live-e2e.yml) (specific SHAs pinned in CI). These tests use Kind +internally. Timeout is 20 minutes. ### Linting @@ -146,7 +148,7 @@ git config --global user.name "Your Name" * Executes: `make all` + `make test-docker` * Triggered on PRs (except changes limited to ignored paths like `**.md`) and pushes (pushes exclude dependabot branches) * **.github/workflows/e2eEnvironment.yml**: KinD-based e2e tests - * Tests Kubernetes 1.33 and 1.34 with KinD v0.30.0 + * Tests Kubernetes versions defined in `jobs.kind.strategy.matrix.version` with KinD (KinD version in `jobs.kind.steps["Install KinD"].with.version`) * Runs `./e2e/live/end-to-end-test.sh -k ` * **.github/workflows/live-e2e.yml**: Live apply e2e tests * Tests with pinned Kubernetes image SHAs @@ -160,6 +162,7 @@ git config --global user.name "Your Name" * **documentation/**: Hugo-based website published to kpt.dev * Run `make serve` from `documentation/` (serves docs locally) * Requires `npm install` first (run in `documentation/`) + * Documentation shold follow the [style guide for documentation](documentation/README.md#style-guide-for-documentation) * **e2e/**: End-to-end test suites * Contains testdata directories for function render/eval tests @@ -183,7 +186,7 @@ git config --global user.name "Your Name" * **Copyright Headers**: All files must have Apache 2.0 license header * Use format: // Copyright YEAR The kpt Authors (or year range if modified) - * Year should match creation year, or creation-to-modification year range + * Year should match creation year, or creation-to-modification year range (see the [instructions in Porch for more details](https://porch.kpt.dev/docs/12_contributing/code-contribution/#update-copyright-on-files)) * **Developer Certificate of Origin (DCO)**: Commits must be signed with -s flag * **Large Features**: Require reviewed and merged design document (use /docs/design-docs/00-template.md as template) * **AI Usage**: Must declare AI usage in the PR description; `Assisted-by: AGENT_NAME:MODEL_VERSION` attribution in @@ -216,7 +219,7 @@ If `make test-docker` fails due to missing Docker/Podman: For e2e live tests (`make test-live-apply`): -* KinD v0.30.0 is auto-installed by CI workflow +* KinD is auto-installed by CI workflow * Requires Docker running in background * Tests use specific Kubernetes image SHAs (see live-e2e.yml matrix) * Timeout is 20 minutes; allow sufficient time