/restructure-commits

description: Restructure branch commits into logical component-based commits for HyperShift PRs
user_invocable: true

Restructure Commits by Component

Reorganize all commits on a feature branch into logical, component-based commits that match HyperShift's architecture.

When to Use

• User asks to "redo commits", "restructure commits", "squash by component", or "organize commits"
• Preparing a branch for PR review with clean commit history
• Branch has many small/WIP commits that should be consolidated

Component Categories and File Mapping

Commits are created in this order. Each commit groups files by architectural boundary.

| Order | Component | Scope | File Patterns | |-------|-----------|-------|---------------| | 1 | API | `api` | `api/` (types, deepcopy, CRD manifests, go.mod) — **excluding** `*_test.go` | | 2 | Vendor | `api` | `vendor/`, `client/`, `cmd/install/assets/hypershift-operator/zz_generated.crd-manifests/` | | 3 | CLI | `cli` | `cmd/cluster/`, `cmd/install/`, `cmd/nodepool/`, `product-cli/` (source, tests, testdata) | | 4 | HO | `hypershift-operator` | `hypershift-operator/`, `support/`, `karpenter-operator/`, `kubevirtexternalinfra/`, `pkg/`, `manifests/`, `shared-ingress/`, `sharedingress-config-generator/` | | 5 | CPO | `control-plane-operator` | `control-plane-operator/`, `control-plane-pki-operator/`, `availability-prober/`, `dnsresolver/`, `etcd-backup/`, `etcd-defrag/`, `etcd-recovery/`, `ignition-server/`, `kas-bootstrap/`, `konnectivity-https-proxy/`, `konnectivity-socks5-proxy/`, `kubernetes-default-proxy/`, `sync-fg-configmap/`, `sync-global-pullsecret/`, `token-minter/` | | 6 | E2E | `e2e` | `test/`, `api/**/*_test.go` | | 7 | Docs | `docs` | `docs/`, `examples/` |

**Excluded from restructuring:** `bin/` (build output), `hack/`, `contrib/`, `hypershift-ci-python/`, `self-managed-azure-ci-setup/`, and `.claude*/` are build tooling, CI helpers, or dev config. If changed, include them in the most relevant commit based on their purpose. When ambiguous, prefer HO.

Procedure

1. Identify merge base and changed files

BASE_BRANCH=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo "main")
MERGE_BASE=$(git merge-base ${BASE_BRANCH} HEAD)
git log --oneline ${MERGE_BASE}..HEAD          # review existing commits
git diff ${MERGE_BASE}..HEAD --name-only | sort # all changed files

2. Reset to merge base (keep changes)

git reset --soft ${MERGE_BASE}  # keep everything staged
git reset HEAD                   # unstage everything

3. Stage and commit each component group

For each component (in order), stage matching files and commit:

# Example: API commit (exclude test files — they belong in E2E)
git add api/ && git reset HEAD 'api/**/*_test.go' 2>/dev/null || true
git commit  # use conventional commit format

# Example: Vendor commit
git add vendor/ client/ \
  "cmd/install/assets/hypershift-operator/zz_generated.crd-manifests/"
git commit

# ... repeat for CLI, HO, CPO, E2E, Docs

4. Verify and force push

git status                                  # must be clean
git log --oneline ${BASE_BRANCH}..HEAD      # verify commit structure
git push --force-with-lease       # requires user confirmation

Commit Message Conventions

**Always invoke the git-commit-format skill first** for the full formatting rules (line length, footer, Co-Authored-By, etc.). This section provides the component-specific type and scope, plus guidance on writing the subject and body.

Writing the subject

1. Look at the actual changes in the component to determine what was done 2. Pick the type and scope from the table below 3. Write a concise subject that summarizes the *purpose* of the changes, not just "update files" 4. Use imperative mood: "add", "update", "remove" — not "added", "adds", "adding"

| Component | Type(Scope) | Example Subject | |-----------|-------------|-----------------| | API | `feat(api):` | `feat(api): add FooBar CRD and platform config` | | Vendor | `chore(api):` | `chore(api): regenerate CRDs, clients, deepcopy, and vendor` | | CLI | `feat(cli):` | `feat(cli): add --foo-bar flags for cluster creation` | | HO | `feat(hypershift-operator):` | `feat(hypershift-operator): add FooBar controller` | | CPO | `feat(control-plane-operator):` | `feat(control-plane-operator): add FooBar controllers` | | E2E | `test(e2e):` | `test(e2e): add FooBar e2e and validation tests` | | Docs | `docs:` | `docs: add FooBar documentation and architecture reference` |

Writing the body

Review the staged changes and write a body that describes *what* was added or changed. Use bullet points when there are multiple distinct changes. The body should give a reviewer enough context to understand the commit without reading every file. Each line must be under 140 characters (gitlint enforced).

Notes

• Vendor commit is always `chore(api):` since it's regenerated output from the API commit
• E2E commit is always `test(e2e):` regardless of what's being tested
• Docs commit has no scope parentheses — just `docs:`

Edge Cases

• **Empty component:** Skip the commit if no files match that component.
• **Support packages:** `support/` goes with HO (commit 4), not CPO.
• **Control plane sidecars:** `control-plane-pki-operator/`, `availability-prober/`, `dnsresolver/`, `etcd-*`, `ignition-server/`, `kas-bootstrap/`, `konnectivity-*`, `kubernetes-default-proxy/`, `sync-fg-configmap/`, `sync-global-pullsecret/`, `token-minter/` all go with CPO (commit 5) since they are control plane components managed by CPO.
• **Shared ingress:** `shared-ingress/` and `sharedingress-config-generator/` go with HO (commit 4), not CPO, since they are part of the hypershift-operator.
• **Karpenter operator:** `karpenter-operator/` goes with HO (commit 4) since it is managed by the hypershift-operator.
• **Shared test fixtures in CPO:** `control-plane-operator/**/testdata/` stays with CPO.
• **Generated CRD install