rebase-framework

name: rebase-framework description: Use when rebasing a branch that modifies the Aptos Move framework and git reports merge conflicts in cached-packages artifacts (`head.mrb` or generated SDK builder `.rs` files under `aptos-move/framework/cached-packages/src/`). Also use when a rebase stops on a binary conflict in `head.mrb`, or when a CI job complains that "Cached framework artifacts are out-of-date" after a rebase.

Rebase with framework cached-packages conflicts

Overview

aptos-move/framework/cached-packages/src/head.mrb is a serialized binary of the compiled Move framework. Sibling files (aptos_framework_sdk_builder.rs, etc.) in the same directory are code-generated from the framework. Neither can be merge-resolved sensibly — they must be rebuilt from the framework sources at the conflict point.

The rule: don't try to 3-way merge cached-packages artifacts. Take one side to unblock git, finish the rebase, then regenerate once at the end with scripts/cargo_build_aptos_cached_packages.sh.

When to use

Conflict markers / git output that should trigger this skill:

CONFLICT (content): Merge conflict in aptos-move/framework/cached-packages/src/head.mrb
warning: Cannot merge binary files: ...head.mrb
CONFLICT in any of aptos-move/framework/cached-packages/src/*.rs
CI error after rebase: ERROR: Cached framework artifacts are out-of-date.

If the conflict is in framework source (e.g., aptos-move/framework/aptos-framework/sources/*.move), resolve that conflict the normal way first — the cached-packages step comes after.

Procedure

Resolve real source conflicts first. Walk the rebase, hand-resolving any .move, .rs, or Cargo.toml conflicts as usual. For cached-packages artifacts, don't try to merge — just unblock git:

# Take the incoming/current side; contents will be regenerated anyway.
git checkout --ours  aptos-move/framework/cached-packages/src/head.mrb
git checkout --ours  aptos-move/framework/cached-packages/src/*.rs
git add              aptos-move/framework/cached-packages/src/head.mrb \
                     aptos-move/framework/cached-packages/src/*.rs
git rebase --continue

--ours vs --theirs doesn't matter for these files — they're about to be overwritten. Pick whichever lets git proceed.

Continue the rebase normally through the remaining commits. If cached-packages conflicts reappear on later commits, repeat step 1. Do not rebuild between commits — it's slow and wasted work.
After the rebase finishes, regenerate the artifacts once from the final tree:
```
scripts/cargo_build_aptos_cached_packages.sh
```
This runs cargo run --profile=ci -p aptos-framework -- update-cached-packages and formats the generated .rs files.

Amend the regenerated artifacts into the framework commit (so history stays clean — bytecode change lives with the source change that caused it):

git status aptos-move/framework/cached-packages/src/
# Identify the commit that touched framework sources. Then:
git add aptos-move/framework/cached-packages/src/head.mrb \
        aptos-move/framework/cached-packages/src/*.rs
# If the framework-changing commit is HEAD:
git commit --amend --no-edit
# Otherwise, fixup + autosquash:
git commit --fixup=<framework-commit-sha>
GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash <framework-commit-sha>^

Verify before pushing:
```
scripts/cargo_build_aptos_cached_packages.sh --check
```
This re-runs the build and fails if any artifact would change — the same gate CI uses.

Quick reference

Situation	Action
Binary conflict in `head.mrb` mid-rebase	`git checkout --ours head.mrb && git add ...` — don't rebuild yet
Conflict in generated `.rs` under `cached-packages/src/`	Same — take one side, rebuild at end
Multiple framework-changing commits in the rebase	Resolve each as above; rebuild once after `rebase --continue` finishes
Conflict in framework `.move` sources	Resolve normally; rebuild step still runs at the end
CI says artifacts out-of-date after push	Run the script, amend/fixup into the framework commit, force-push

Common mistakes

Trying to merge head.mrb by hand or with a mergetool. It's a binary blob — there's nothing to merge. Always regenerate.
Rebuilding after every conflicting commit during the rebase. Wastes minutes per commit. Rebuild once at the end.
Committing the regenerated artifacts as a separate "rebuild framework" commit. Reviewers expect the bytecode delta to live with the Move source change. Use --amend or --fixup to keep them together.
Skipping --check before pushing. CI runs the same check; failing it round-trips the PR.
Forgetting the generated .rs files. The script regenerates both head.mrb and aptos-move/framework/cached-packages/src/*.rs. Stage both.

aptos-move/framework/cached-packages/README.md — upstream docs for the artifact.
Repo CLAUDE.md note: "After modifying Move code in aptos-move/framework/: cargo build -p aptos-cached-packages" — that's the per-edit workflow; this skill covers the rebase variant.