Restructure Commits

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.

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"

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 manifests: cmd/install/assets/hypershift-operator/zz_generated.crd-manifests/ goes with Vendor (commit 2), not CLI.
• API go.mod: api/go.mod goes with API (commit 1), not Vendor.
• API test files: api/**/*_test.go (UX API validation tests) go with E2E (commit 6), not API. Stage API non-test files first, then include API test files when staging E2E.
• Documentation files: docs/ and examples/ go with Docs (commit 7), not Vendor. This includes mkdocs config, how-to guides, architecture references, and aggregated docs. The docs/content/reference/api.md (generated API reference) also goes here.
• Build/CI tooling: hack/, contrib/, hypershift-ci-python/, self-managed-azure-ci-setup/ are not mapped to a default component. Include in the most relevant commit based on purpose, or HO when ambiguous.

Quick Checklist

• Determined base branch from PR (defaults to main)
• Reviewed all changed files before starting
• Reset with --soft (no data loss)
• Committed in correct order: API, Vendor, CLI, HO, CPO, E2E, Docs
• Working tree is clean after all commits
• Confirmed force push with user before executing