OpenParable
Skip to content
← Back to skills

Rebase Framework

Development
rebase-framework

Rebase Framework is an Agent Skill for development published in the aptos-labs/aptos-core repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/aptos-labs/aptos-core/blob/HEAD/.cursor/skills/rebase-framework/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/rebase-framework, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

  1. 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.

  2. 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.

  3. 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.

  4. 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>^
    
  5. 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

SituationAction
Binary conflict in head.mrb mid-rebasegit 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 rebaseResolve each as above; rebuild once after rebase --continue finishes
Conflict in framework .move sourcesResolve normally; rebuild step still runs at the end
CI says artifacts out-of-date after pushRun 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.

Related

  • 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.