rebase

Rebase che-code Against Upstream VS Code

End-to-end workflow for rebasing the che-code fork against a new upstream VS Code release. This skill coordinates three other skills (validate-rebase-rules, fix-rebase-rules, test-rebase-rules) along with rebase.sh.

Input

The user provides the target VS Code release in one of three forms:

• Full branch name: release/1.120 — used as-is
• Short version: 1.120 — expanded to release/1.120
• Issue URL: https://github.com/eclipse-che/che/issues/23823 — fetch the issue title/body via gh issue view -R eclipse-che/che <number>, extract the version (pattern: 1.NNN.x or 1.NNN), expand to release/1.NNN

If the user provides an issue URL, store it for later use in the PR description ("What issues does this PR fix?" section).

If not provided, ask.

Version validation

All three input forms go through the same validation:

1. Format check: the resolved value must match release/1.NNN (e.g. release/1.120)
2. Greater-than check: read CURRENT_UPSTREAM_VERSION from rebase.sh, parse numeric parts, the target must be strictly greater. For example, if CURRENT_UPSTREAM_VERSION="release/1.116" and the user provides 1.115, inform them: "Version 1.115 is not valid — the current upstream version is already release/1.116"
3. Upstream existence check: verify the branch exists: git ls-remote upstream-code refs/heads/release/1.NNN

If all checks pass: proceed silently. If any check fails: inform user what went wrong and ask for the correct version.

Branch Management

After validating the target version:

1. Read target_remote from .claude/skills/rebase/rebase-config.yaml and ensure it is configured as a git remote named target (add it if not: git remote add target <url>)
2. Fetch the target remote's main: git fetch target main
3. Check current branch: git branch --show-current
4. If on main: create and switch to a new branch based on target/main:

   git checkout -b alignment-with-upstream-1-<version> target/main
   

   For example, target release/1.120 produces branch alignment-with-upstream-1-120.
5. If already on the matching alignment-with-upstream-1-<version> branch: continue on it
6. If on any other branch (including a different alignment-with-upstream-*):
   • If there are uncommitted changes (git status --porcelain): warn the user and stop
   • If clean: create and switch to a new branch based on target/main

Prerequisites

git remote get-url upstream-code || git remote add upstream-code https://github.com/microsoft/vscode
git fetch upstream-code

Commit Strategy

Each logical step produces a separate commit following single responsibility. Every commit becomes a checkbox in the PR description. Conditional commits are only created when there is work to do.

1. Update upstream version references — rebase.sh (PREVIOUS_UPSTREAM_VERSION, CURRENT_UPSTREAM_VERSION)
2. Pre-rebase conflict analysis — .rebase/<ver>/pre-rebase-report.md
3. Audit and update dependency pins (CVE fixes) — .rebase/<ver>/dependency-audit.md + .rebase/add/, .rebase/override/, code/ changes
4. Create rebase rules for uncovered files — new .rebase/replace/ + elif entries (conditional)
5. Fix and update rebase rules — fixed .rebase/replace/ + missing elif entries (conditional)
6. Rebase against upstream — merge commit from rebase.sh
7. Fix rebase errors — npm install / EOVERRIDE fixes (conditional)
8. Fix compilation errors — code fixes (conditional)
9. Update artifacts lock — build/artifacts/artifacts.lock.yaml

Reports

All reports are written to .rebase/<version>/ (e.g. .rebase/1.120/). Create the directory at the start of the rebase:

mkdir -p .rebase/<version>

Reports generated during the process:

• .rebase/<ver>/pre-rebase-report.md — conflict classification from pre-rebase.sh
• .rebase/<ver>/dependency-audit.md — dependency pin audit results
• .rebase/<ver>/rebase-errors.md — Phase 2 errors if unfixed (conditional)
• .rebase/<ver>/compilation-errors.md — Phase 3 compilation errors if unfixed (conditional)

Phase 1 — Prepare

Step 1: Update version references in rebase.sh

Read rebase.sh and extract the current values:

• PREVIOUS_UPSTREAM_VERSION — the version that was previously rebased to
• CURRENT_UPSTREAM_VERSION — the version for the current/next rebase

Update them:

# PREVIOUS_UPSTREAM_VERSION becomes what was CURRENT_UPSTREAM_VERSION
# CURRENT_UPSTREAM_VERSION becomes the new target

For example, if CURRENT was release/1.108 and the new target is release/1.120:

PREVIOUS_UPSTREAM_VERSION="release/1.108"
CURRENT_UPSTREAM_VERSION="release/1.120"

Commit: "Update upstream version references"

Step 2: Fetch the new upstream branch

git fetch upstream-code <target-version>

Step 3: Run pre-rebase validation

Run pre-rebase.sh to discover all conflicts and classify them:

bash pre-rebase.sh

This performs a trial subtree merge on a temp branch, classifies every conflicting file, and writes .rebase/<ver>/pre-rebase-report.md. The report starts with a raw list of all conflicting files, then categorizes them as:

• RULED — has .rebase/ rules and an elif entry in resolve_conflicts(). Ready.
• LOCK — package-lock.json files. Auto-handled by the generic resolve_package_lock function.
• TAKE_THEIRS — no che-specific changes vs previous upstream. Safe to take upstream.
• MISSING_ELIF — has .rebase/ rules but no elif entry. The smart fallback handles these, but explicit entries are recommended.
• NEEDS_RULE — che-specific changes exist but no .rebase/ rule covers them. These are handled in Step 4.

If pre-rebase.sh exits with code 1, there are NEEDS_RULE files — proceed to Step 4.

Commit: "Pre-rebase conflict analysis" (includes the report file)

Step 3b: Audit dependency pins

Audit all dependency version pins in .rebase/add/ and .rebase/override/ files against the new upstream. Follow the process in .claude/skills/dependency-rebase-rules/SKILL.md:

1. Compare every pinned version against what upstream uses at the target release
2. Classify each pin as ACTIVE, REDUNDANT, or OUTDATED
3. Write the audit report to .rebase/<ver>/dependency-audit.md
4. Apply recommended changes (remove redundant pins, move pins to override, update code/ files)
5. After removing redundant pins, verify lock file stability (npm install should produce no changes)

Do not stop for user confirmation — apply changes and document everything in the report for review in the PR.

Commit: "Audit and update dependency pins (CVE fixes)" (includes the report + all pin changes)

Step 4: Create missing rules (if NEEDS_RULE files exist)

For each NEEDS_RULE file in the pre-rebase report, use the fix-rebase-rules skill (read .claude/skills/fix-rebase-rules/SKILL.md), specifically its "Handling uncovered Che-specific changes" workflow:

1. Read the che-code file to understand the che-specific modification
2. Read the upstream file at PREVIOUS_UPSTREAM_VERSION to see the original code
3. Create a rule: from = upstream snippet, by = che-modified version
4. For source files (.ts, .html, etc.) — creates .rebase/replace/<path>.json
5. For JSON files (package.json) — creates .rebase/add/ and/or .rebase/override/ rules
6. Also updates rebase.sh routing — adds the elif entry

If rule creation fails for a file: check whether that file actually conflicts in the rebase (from the pre-rebase report conflict list). If it conflicts, this is a real blocker — stop for manual review. If it does not conflict, log as ERROR in the pre-rebase report and continue.

Commit (conditional): "Create rebase rules for uncovered files"

Step 5: Add missing elif entries (if MISSING_ELIF files exist)

For files that have .rebase/ rules but no elif entry in resolve_conflicts(), add the entry following the existing patterns.

Step 6: Validate existing rules against the NEW upstream

Run the validate-rebase-rules skill (read .claude/skills/validate-rebase-rules/SKILL.md). This produces rebase-rules-validation.md.

Key point: the validation now runs against the new CURRENT_UPSTREAM_VERSION, so it will catch all from values that changed between the old and new upstream.

Step 7: Fix stale rules

If the validation report has ERROR-level items, run the fix-rebase-rules skill (read .claude/skills/fix-rebase-rules/SKILL.md).

Common issues:

• Stale from values — upstream changed the code that from was matching. The fix skill updates from to match the new upstream and by to produce the current che-code result.
• Missing rules — the "Uncovered Che-specific Changes" section lists code that would be lost. Create new rules for these.

If a fix fails for a file: same logic as Step 4 — if the file conflicts in the rebase, stop; if not, log as ERROR and continue.

Step 8: Test the fixed rules

Run the test-rebase-rules skill (or directly):

bash .claude/skills/test-rebase-rules/run-all-tests.sh

All tests must pass (or show only cosmetic warnings) before proceeding. If a test fails, re-fix the rule and re-test (retry loop). If repeated attempts fail, apply the same conflict/no-conflict logic from Steps 4 and 7.

Commit (conditional, covers Steps 5-8): "Fix and update rebase rules"

Phase 2 — Rebase

Step 9: Run the rebase

bash rebase.sh

Expected outcomes:

Step 10: Handle remaining conflicts (if any)

If rebase.sh failed, tr

Content truncated.