From 8e6ffe1f65837cbce8ea62da3a9e8b41d408a4e9 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Wed, 28 Oct 2026 05:16:38 +0000 Subject: [PATCH 1/2] docs: explain serial verification and CI delegation Document ordered CAPI verification and workflow reachability through Make entrypoints. Preserve upstream contributor and development guidance. Assisted-by: LLM Signed-off-by: Chai Bot --- CONTRIBUTING.md | 2 +- DEVELOPMENT.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b560af7c4ef..591918ba36c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,7 +34,7 @@ The following guidelines will help ensure a smooth contribution process for both This project uses [Prow](https://docs.ci.openshift.org/) and [GitHub Actions](https://github.com/openshift/hypershift/actions) for CI. Lightweight checks (linting, unit tests, verification) run automatically on pushes and pull requests. E2E tests that consume real cloud infrastructure only run after a reviewer grants `/lgtm`, to avoid unnecessary resource usage on work-in-progress PRs. -**Adding CI targets:** When you add a new `make` target to `verify-parallel` or any other CI-facing Makefile target, you must also add it to the corresponding GitHub Actions workflow (e.g., `.github/workflows/verify-reusable.yaml` for verify targets, or as a new "reusable" target). GitHub Actions provide fast feedback on PRs; Prow runs heavier e2e tests. Targets that only exist in the Makefile without a matching GH Actions step will not run in CI. +**Adding CI targets:** Ensure each new check is reachable from the corresponding GitHub Actions workflow, either through a Makefile entrypoint it already invokes or through a workflow step. For example, `.github/workflows/verify-reusable.yaml` runs `make verify-ci`, which delegates to `verify-serial-targets`; changing that group's contents does not require a separate workflow step. Adding a target only to `verify-parallel-targets` does not automatically include it in that workflow. GitHub Actions provide fast feedback on PRs; Prow runs heavier e2e tests. See hack/github-actions-runner/README.md for details. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index fbf5cf1fec66..0abcd6fcf1bd 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -237,7 +237,7 @@ make verify-capi-decoupling # Check the invariants below without a full CI run Because each provider is a separate module reached through `replace`, `go build ./...` in the root module compiles only the provider subpackages something imports — a broken `exp/api` package stays invisible until CRD generation. It also means the localized `capicore` types and the upstream CAPI types they were copied from are **distinct Go types**: code merged from upstream that names `clusterv1beta1` or `capiv1` where a file already uses `capicore` will not compile, and the error does not say why. -`make verify-capi-decoupling` (`hack/verify-capi-decoupling.sh`) checks this in seconds: no provider module may require or import `sigs.k8s.io/cluster-api`, every subpackage of every provider module must build, and the packages that consume `capicore` types must vet. It runs in `verify-parallel` and `verify-ci`; run it locally after **any merge or rebase onto main that touched provider types**, which is where the alias mismatch usually arrives from. +`make verify-capi-decoupling` (`hack/verify-capi-decoupling.sh`) checks this in seconds: no provider module may require or import `sigs.k8s.io/cluster-api`, every subpackage of every provider module must build, and the packages that consume `capicore` types must vet. It runs after `verify-capi-sync` in `verify-serial-targets`, invoked by `verify` and `verify-ci`; run it locally after **any merge or rebase onto main that touched provider types**, which is where the alias mismatch usually arrives from. The sync process (`hack/capi-sync-provider.sh`) for each provider: 1. Downloads the upstream module into the Go module cache via `go mod download` From 6ce78a690c39690bf37eaf3708f9b92de50543e4 Mon Sep 17 00:00:00 2001 From: Chai Bot Date: Wed, 28 Oct 2026 05:16:38 +0000 Subject: [PATCH 2/2] build(verify): sequence conflicting CAPI checks before readers Run provider synchronization before decoupling and independent parallel checks. Keep the upstream CI lint check after serial verification to avoid reading a regenerating tree. Preserve Bash 3.2 handling of empty optional copier arguments. Assisted-by: LLM Signed-off-by: Chai Bot --- Makefile | 20 ++++++++++++++++---- hack/capi-sync-provider.sh | 2 +- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index af3905b76d35..f899a62431d2 100644 --- a/Makefile +++ b/Makefile @@ -182,16 +182,28 @@ verify-crd-schema: $(CRD_SCHEMA_CHECK) ## Verify CRD schemas for breaking change --crd-dir=cmd/install/assets/crds/hypershift-operator \ --crd-dir=karpenter-operator/controllers/karpenter/assets/zz_generated.crd-manifests -.PHONY: verify-parallel -verify-parallel: verify-codespell verify-codecov verify-api-deps verify-crd-schema verify-capi-sync verify-capi-decoupling lint cpo-container-sync run-gitlint verify-docs-nav verify-tekton-pipeline-pairs +# Targets that conflict, such as deleting or mutating a directory another target +# reads, must move to verify-serial-targets instead of running in parallel here. +.PHONY: verify-parallel-targets +verify-parallel-targets: verify-codespell verify-codecov verify-api-deps verify-crd-schema lint cpo-container-sync run-gitlint verify-docs-nav verify-tekton-pipeline-pairs + +# Run target checks sequentially after preparation. +.PHONY: verify-serial-targets +verify-serial-targets: + # Sync regenerates provider sources that decoupling builds and lint reads. + $(MAKE) verify-capi-sync + $(MAKE) verify-capi-decoupling .PHONY: verify-ci -verify-ci: generate update staticcheck fmt vet lint verify-api-deps verify-crd-schema verify-capi-decoupling verify-docs-nav verify-tekton-pipeline-pairs ## Run the same checks as the GHA verify workflow. +verify-ci: generate update staticcheck fmt vet verify-api-deps verify-crd-schema verify-docs-nav verify-tekton-pipeline-pairs ## Run the same checks as the GHA verify workflow. + $(MAKE) verify-serial-targets + $(MAKE) lint $(MAKE) verify-git-clean .PHONY: verify verify: generate update staticcheck fmt vet - $(MAKE) -j verify-parallel + $(MAKE) verify-serial-targets + $(MAKE) -j verify-parallel-targets $(MAKE) verify-git-clean .PHONY: verify-quick diff --git a/hack/capi-sync-provider.sh b/hack/capi-sync-provider.sh index 082aa495b2a3..34d0d154c5d3 100755 --- a/hack/capi-sync-provider.sh +++ b/hack/capi-sync-provider.sh @@ -157,7 +157,7 @@ while read -r pkg; do [[ -n "$prefix" ]] || continue allow_args+=(--allow "$prefix") done < <(allow_prefixes "$PROVIDER:$sub") - copy_types "$SRC/$sub" "$DST_DIR/$sub" "${allow_args[@]}" + copy_types "$SRC/$sub" "$DST_DIR/$sub" ${allow_args[@]+"${allow_args[@]}"} done < <(provider_packages) while read -r glob; do