Add multi-repo upgrade and dependency maintenance utility

scripts/go-upgrade/README.md

@@ -0,0 +1,157 @@
+# Multi-Repo Upgrade Utility
+
+Multi-repository upgrade and dependency maintenance tool for the kptdev ecosystem.
+
+Coordinates Go version upgrades, linter version upgrades, and cross-repository dependency updates across 4 interdependent repositories:
+
+```
+krm-functions-sdk  (leaf — no upstream deps)
+        ↓
+    ┌───┴───────────────┐
+    ↓                   ↓
+   kpt          krm-functions-catalog
+    ↓                   ↓
+    └───────┬───────────┘
+            ↓
+          porch          (top — depends on all three)
+```
+
+## Quick Start
+
+```bash
+# Preview what would change
+./upgrade.sh go-version --dry-run
+
+# Upgrade Go version across all repos
+./upgrade.sh go-version
+
+# Upgrade a single repo
+./upgrade.sh go-version --repo=porch
+
+# Full upgrade: Go + lint + cross-deps
+./upgrade.sh all
+
+# Full upgrade + push PRs (one-shot)
+./upgrade.sh all --push
+
+# Two-step workflow: upgrade, review diffs, then push separately
+./upgrade.sh go-version
+# ... inspect git diff in workspace/ ...
+./upgrade.sh push --for=go-version
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|---|---|
+| `go-version` | Bump `go` directive in all `go.mod` files, then verify (tidy, fmt, vet, build) |
+| `lint-version` | Bump `GOLANGCI_LINT_VERSION` in Makefiles |
+| `cross-deps` | Upgrade dependencies owned by other repos in the set to their latest version |
+| `all` | Run `go-version` + `lint-version` + `cross-deps` sequentially |
+| `push` | Create branch, commit, push, and raise draft PR for pending workspace changes |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--repo=NAME` | Scope to a single repository |
+| `--continue` | Don't fail-fast; accumulate errors and report at end |
+| `--dry-run` | Show what would change without modifying files |
+| `--push` | After successful operations, create branch, commit, push, and raise draft PR |
+| `--for=CMD` | With `push` subcommand: specify which upgrade was done (default: `all`) |
+
+## Configuration
+
+Edit `config.env` to change target versions, repositories, or exclusions.
+
+### Fork Owner
+
+The `FORK_OWNER` variable controls which GitHub org/user to clone from. All repo URLs are derived from it. Defaults to `Nordix` (shared development forks). PRs always target upstream `kptdev/*` regardless of fork owner.
+
+```bash
+# Use your personal fork
+FORK_OWNER=myuser ./upgrade.sh go-version
+
+# Default: uses Nordix forks
+./upgrade.sh go-version
+```
+
+### Target Versions
+
+```bash
+TARGET_GO_VERSION="1.26.5"
+TARGET_GOLANGCI_LINT_VERSION="2.12.2"
+```
+
+### Repository Format
+
+```
+NAME|GIT_URL|BRANCH|PR_TARGET
+```
+
+- `NAME` — identifier used with `--repo` and in output
+- `GIT_URL` — SSH clone URL
+- `BRANCH` — branch to clone and base for PRs
+- `PR_TARGET` — GitHub `owner/repo` for cross-fork PRs (empty = PR against same repo)
+
+### Exclusions
+
+- `EXCLUDE_MODULES` — glob patterns for modules to skip entirely
+- `EXCLUDE_DEPS_GLOBAL` — dependencies never upgraded by `cross-deps`
+- `EXCLUDE_DEPS_REPO` — per-repo dependency exclusions
+
+## How It Works
+
+1. **Clone** repos into `workspace/` (reuses existing clones)
+2. **Clean state** — ensures base branch, discards leftover changes, detects pollution
+3. **Run subcommand** — modifies files, verifies each module
+4. **Push** (if `--push`) — creates dated branch, commits, pushes, raises draft PR
+
+### Verification Pipeline
+
+Each module is verified with `GOWORK=off`:
+```
+go mod tidy → go fmt ./... → go vet ./... → go build ./...
+```
+
+Modules are built standalone to respect their own dependency pins, avoiding false conflicts from workspace version unification.
+
+### Cross-Deps Resolution
+
+For each module, dependencies owned by another repo in the set are upgraded to the latest published version. Resolution order:
+1. GitHub releases API
+2. Go module proxy (stable tags, excluding alpha/dev)
+3. Go module proxy (all tags)
+4. `@latest` pseudo-version
+
+## File Structure
+
+```
+scripts/go-upgrade/
+├── upgrade.sh          # Main entry point
+├── config.env          # Configuration (versions, repos, exclusions)
+├── README.md           # This file
+└── lib/
+    ├── common.sh       # Logging, colors, failure tracking, helpers
+    ├── workspace.sh    # Clone, clean state, module discovery
+    ├── verify.sh       # tidy/fmt/vet/build pipeline
+    ├── versions.sh     # go-version + lint-version subcommands
+    ├── deps.sh         # cross-deps subcommand
+    └── push.sh         # Branch/commit/push/PR creation
+```
+
+## Design Decisions
+
+- **`GOWORK=off` everywhere** — each module is built standalone respecting its own `go.mod` pins
+- **No sequential releases needed for Go bumps** — each repo builds independently; PRs can be merged in parallel
+- **Cross-fork PRs** — pushes to fork (`Nordix` or personal), raises PRs against upstream `kptdev/*` via GraphQL `createPullRequest` mutation with `headRepositoryId`
+- **Fail-fast by default** — first failure stops execution (override with `--continue`)
+- **Draft PRs** — all PRs are created as drafts for review before merge
+- **Signed commits** — all commits use `--signoff` for DCO compliance
+
+## Prerequisites
+
+- `go` (matching `TARGET_GO_VERSION`)
+- `jq`
+- `gh` (GitHub CLI, only needed with `--push`)
+- SSH access to configured repositories

scripts/go-upgrade/config.env

@@ -0,0 +1,64 @@
+# 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.
+
+# go-upgrade configuration
+# See README.md for full documentation of each option.
+
+# --- Fork owner (override via environment) ---
+# Controls which GitHub org/user to clone from.
+# Override: FORK_OWNER=myuser ./upgrade.sh go-version
+FORK_OWNER="${FORK_OWNER:-Nordix}"
+
+# --- Target versions ---
+TARGET_GO_VERSION="1.26.5"
+TARGET_GOLANGCI_LINT_VERSION="2.12.2"
+
+# --- Workspace ---
+WORKSPACE_DIR="workspace"
+
+# --- Repositories ---
+# Format: NAME|GIT_URL|BRANCH|PR_TARGET
+#
+# PR_TARGET: GitHub owner/repo to raise PR against.
+#            Leave empty to PR against the same repo derived from GIT_URL.
+#
+# Ordered by dependency chain (least dependent first).
+REPOS=(
+  "krm-functions-sdk|git@github.com:${FORK_OWNER}/krm-functions-sdk.git|main|kptdev/krm-functions-sdk"
+  "kpt|git@github.com:${FORK_OWNER}/kpt.git|main|kptdev/kpt"
+  "krm-functions-catalog|git@github.com:${FORK_OWNER}/krm-functions-catalog.git|main|kptdev/krm-functions-catalog"
+  "porch|git@github.com:${FORK_OWNER}/porch.git|main|kptdev/porch"
+)
+
+# --- Lint Makefile locations (per repo) ---
+declare -A LINT_MAKEFILES=(
+  [krm-functions-sdk]="go/Makefile"
+  [kpt]="Makefile"
+  [krm-functions-catalog]="functions/go/Makefile"
+  [porch]="make/go.mk"
+)
+
+# --- Exclusions ---
+
+# Modules to skip entirely (glob patterns, matched against relative path from workspace)
+EXCLUDE_MODULES=(
+  "*/archived/*"
+  "porch/third_party/*"
+)
+
+# Global dependency exclusions (applies to all repos in cross-deps)
+EXCLUDE_DEPS_GLOBAL=()
+
+# Per-repo dependency exclusions (space-separated)
+declare -A EXCLUDE_DEPS_REPO=()

scripts/go-upgrade/lib/common.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+# 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.
+
+# Common utilities: logging, colors, failure tracking, helpers.
+# Sourced by upgrade.sh — do not execute directly.
+
+# --- Colors ---
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+# --- Logging ---
+log()  { echo -e "${GREEN}[INFO]${NC} $*"; }
+warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
+err()  { echo -e "${RED}[ERR]${NC} $*" >&2; }
+step() { echo -e "${CYAN}[>>]${NC} $*"; }
+
+# --- Failure tracking ---
+FAILURES=()
+
+record_failure() {
+  FAILURES+=("$1")
+  if [[ "$FAIL_FAST" == true ]]; then
+    err "Fail-fast: $1"
+    exit 1
+  fi
+}
+
+report_failures() {
+  if [[ ${#FAILURES[@]} -eq 0 ]]; then
+    log "All operations completed successfully."
+    return 0
+  fi
+  err "Failures (${#FAILURES[@]}):"
+  for f in "${FAILURES[@]}"; do
+    echo -e "  ${RED}✗${NC} $f"
+  done
+  return 1
+}
+
+# --- Workspace path ---
+WORKSPACE=""
+ws() {
+  if [[ -z "$WORKSPACE" ]]; then
+    WORKSPACE="${SCRIPT_DIR}/${WORKSPACE_DIR}"
+  fi
+  echo "$WORKSPACE"
+}
+
+# Relative path for display
+rel_path() { echo "${1#$(ws)/}"; }
+
+# --- Repo entry parsing ---
+# Format: NAME|GIT_URL|BRANCH|PR_TARGET
+repo_name() { IFS='|' read -r name _ _ _ <<< "$1"; echo "$name"; }
+
+repo_url() { IFS='|' read -r _ url _ _ <<< "$1"; echo "$url"; }
+
+repo_base_branch() { IFS='|' read -r _ _ branch _ <<< "$1"; echo "$branch"; }
+
+repo_pr_target() {
+  local entry="$1"
+  IFS='|' read -r _ url _ pr_target <<< "$entry"
+  if [[ -n "$pr_target" ]]; then
+    echo "$pr_target"
+  else
+    echo "$url" | sed -E 's|.*[:/]([^/]+/[^/]+)\.git$|\1|'
+  fi
+}
+
+# Return repos filtered by --repo flag
+active_repos() {
+  for entry in "${REPOS[@]}"; do
+    local name
+    name="$(repo_name "$entry")"
+    if [[ -z "$FILTER_REPO" || "$name" == "$FILTER_REPO" ]]; then
+      echo "$entry"
+    fi
+  done
+}
+
+# --- Exclusion checks ---
+is_excluded_module() {
+  local mod_path="$1"
+  for pattern in "${EXCLUDE_MODULES[@]}"; do
+    # shellcheck disable=SC2053
+    if [[ "$mod_path" == $pattern ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+is_excluded_dep() {
+  local repo="$1" dep="$2"
+  for d in "${EXCLUDE_DEPS_GLOBAL[@]+"${EXCLUDE_DEPS_GLOBAL[@]}"}"; do
+    [[ "$dep" == "$d" || "$dep" == "$d/"* ]] && return 0
+  done
+  local repo_exclusions="${EXCLUDE_DEPS_REPO[$repo]:-}"
+  for d in $repo_exclusions; do
+    [[ "$dep" == "$d" || "$dep" == "$d/"* ]] && return 0
+  done
+  return 1
+}
+
+# --- Dependency checks ---
+check_deps() {
+  command -v jq >/dev/null 2>&1 || { err "jq is required but not installed"; exit 1; }
+  command -v go >/dev/null 2>&1 || { err "go is required but not installed"; exit 1; }
+  if [[ "$GIT_PUSH" == true ]]; then
+    command -v gh >/dev/null 2>&1 || { err "gh (GitHub CLI) is required for --push"; exit 1; }
+  fi
+
+  # Validate that the target Go version is available
+  local installed_go
+  installed_go="$(go version | grep -oP 'go\K[0-9]+\.[0-9]+(\.[0-9]+)?')"
+  if [[ "$installed_go" != "$TARGET_GO_VERSION" ]]; then
+    err "Installed Go version is ${installed_go}, but TARGET_GO_VERSION is ${TARGET_GO_VERSION}"
+    err "Install Go ${TARGET_GO_VERSION} or update TARGET_GO_VERSION in config.env"
+    exit 1
+  fi
+}