Index of every page on this site: llms.txt
All skills
microsoft avatar

/nvx-rebase-openvmm-chain

@fef56ac
by microsoftmicrosoft/nvx857 stars
66
Run it yourself

Rebase or reorganize the OpenVMM microVM chain onto the latest upstream main as a new feature/microvm/release branch, validate and publish it, pin it in NVX with a remapped roadmap, and land it. Use for microVM release rebases and reorganizations, chain commits that upstream landed, rebase conflicts and fixups, and the release landing order.

  • 2 files
  • 12.9 KB
  • Updated 4 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/microsoft/nvx/nvx-rebase-openvmm-chain

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈92 tokens for metadata: the name and description. ≈2.7k when used: this file. ≈456 more on demand in 1 file.

Description uses 4.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈370 characters, or 4.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Rebase The OpenVMM MicroVM Chain

feature/microvm/dev of microsoft/openvmm carries the microVM chain on a fork base taken from upstream main. A release moves the whole chain onto a newer upstream main as feature/microvm/release/vX.Y:

  • A rebase, the next minor version, replays every commit, drops those whose changes upstream landed, resolves conflicts in place, and adds fixups at its tip for upstream changes that break the chain without a conflict.
  • A reorganization, the next major version, also folds those fixups into the commits that they fix and regroups commits so that every commit builds on the new base; it may change behavior.

It rewrites shared branches of microsoft/openvmm, so push only when the user asks. Its NVX commits and pull request follow nvx-promote-openvmm-pin, except as section 6 says. Commands use python3; use python on Windows.

1. State

  • Preserve dirty state in both repositories, and work on the chain in a worktree of openvmm/ outside both checkouts, never in openvmm/ itself.

  • Use a remote of openvmm/ that resolves to microsoft/openvmm; add one with git -C openvmm remote add REMOTE https://github.com/microsoft/openvmm.git when none does, since older checkouts name nanvix/openvmm origin.

  • Record the state:

    python3 scripts/openvmm_release.py state --remote REMOTE --kind rebase

    It fetches upstream main, feature/microvm/dev, and the release branches; stops on a shallow history; and reports old_head, old_base (which must be the roadmap's fork base), the previous release and its head, NVX's pin, new_base and its date, the next version (refusing one that exists), the open OpenVMM pull requests into feature/microvm/dev with their stacked layers, and NVX's open pin promotions. Pass --kind reorganization for a major version, and ask which kind it is unless the user said so.

  • Settle the prerequisites: land each open OpenVMM pull request in dependency order, as nvx-promote-openvmm-pin describes, or agree with the user to carry its commits into the release. Retarget a stacked pull request to feature/microvm/dev with gh pr edit only once its parent landed, after gh stack unstack when a native stack locks its base. Merge or close NVX's open pin promotions, since a revision of the old chain leaves the branch that .gitmodules tracks once feature/microvm/dev moves.

2. Choose What To Drop

python3 scripts/openvmm_release.py drops --old-base OLD_BASE --old-head OLD_HEAD --new-base NEW_BASE

It lists upstream's commits since the old base, the chain commits whose patches upstream already has, and the roadmap's open upstream pull requests with their states. Drop each commit whose change upstream merged, even in a revised form, and adapt the later commits to upstream's version. Drop a commit that an upstream change supersedes only once you have shown that upstream covers what it does. Record each drop's former position, fork commit, roadmap PR, upstream pull request, and upstream commit for the roadmap.

3. Replay The Chain

  1. Add the worktree with an absolute directory outside both checkouts, and replay the chain onto the new base, changing each dropped commit's pick to drop:

    git -C openvmm worktree add -b microvm-release-VERSION DIRECTORY OLD_HEAD
    git -C DIRECTORY rebase -i --onto NEW_BASE OLD_BASE
  2. Keep commit signing on; never pass --no-gpg-sign or override commit.gpgsign, and stop if signing fails. Drop no other commit without the user's approval, and record each commit that the rebase drops as empty.

  3. Resolve each conflict where it occurs, keeping the intent of both upstream's change and the commit, and record its position, commit, the upstream pull request that it conflicts with, and the resolution:

    • Regenerate generated pipelines with cargo xflowey regen instead of merging their text, and require cargo xtask fmt --pass verify-flowey at every commit that changes flowey/ or the generated files.
    • In Cargo.lock, keep both sides' entries, and require cargo check --locked at that commit.
  4. Fix upstream changes that break the chain without a conflict, which builds and tests find. In a rebase, add a fixup commit at the tip for each, naming the upstream pull request and the commits that it folds into at the next reorganization. In a reorganization, fold each fix into the commits that it fixes, keeping the anchor's author and date and crediting the folded commits' authors with Co-authored-by; keep commits that can go upstream on their own apart. Record where each fix went.

  5. Check the chain:

    python3 scripts/openvmm_release.py check-chain --dir DIRECTORY --new-base NEW_BASE --old-base OLD_BASE --old-head OLD_HEAD

    It requires no merges and a signature on every commit, good wherever this host can verify it; it lists the signatures that this host cannot verify, with how to let git verify them, and gives the range diff's counts. Claim tree equivalence only for equal trees; a reorganization that changes behavior claims neither tree nor patch equivalence and rests on per-commit builds and tests.

4. Validate The Chain

  • python3 scripts/openvmm_release.py check-commits --dir DIRECTORY --new-base NEW_BASE runs rustfmt on the changed Rust files, cargo check --locked --workspace --all-targets, and cargo xtask fmt --pass lints at each selected commit, on x86_64 Linux and on x86_64 Windows: every commit of a reorganization, and at least the commits of a rebase that a conflict or a fixup changed (--commits SHA...). In a rebase, an intermediate failure that an upstream change causes is acceptable with the tip fixup that resolves it; the head must pass.
  • At the head, run the OpenVMM instructions' gates for each package that a conflict, fixup, or fold changed: cargo xtask fmt, cargo clippy --workspace --all-targets -- -D warnings on Linux and Windows, the packages' unit tests, and the microVM VMM tests through cargo xflowey vmm-tests-run --filter "test(microvm)". Report each platform that you could not use as left to OpenVMM CI.
  • OpenVMM's CI does not run NVX's workloads, so section 6 runs NVX's scenarios on the new head too.

5. Publish The Release Branch

When the user asks:

python3 scripts/openvmm_release.py publish --dir DIRECTORY --version VERSION --remote REMOTE --push

It pushes the release branch without force, which runs OpenVMM CI, so the release needs no OpenVMM pull request; waits for that run to appear; and checks it with nvx.py check-openvmm-ci. The six jobs that NVX requires must pass. Before calling another failed job unrelated, find its root cause and show that it fails on upstream main or on the previous release too. Fix a failure that the chain causes: a rebase gets a tip fixup, pushed without force; a reorganization rewrites the branch, which needs the user's approval, a lease on the published head, and a feature/microvm/dev that does not point to it yet. Tests that encode ABI versions change with a reorganization that restarts them.

6. Pin The Release In NVX

Build the NVX branch, its two commits, and its pull request as sections 3, 5, and 6 of nvx-promote-openvmm-pin describe, with these differences:

  • No commit of the old chain is an ancestor of the new head, so its roadmap section does not apply: remap the whole roadmap as references/remap.md describes, then run python3 scripts/openvmm_pin.py check-roadmap --worktree.
  • Name the commits openvmm: pin microVM VERSION, rebased onto upstream main (or reorganized onto upstream main) and doc: map the OpenVMM roadmap onto the microVM VERSION rebase (or reorganization).
  • The comparisons of what nvx copies from OpenVMM decide the gitlink commit's coordinated changes. A release that changes an ABI changes more, such as the CLI's compatibility policy, the snapshot manifest's versions, SOURCE-MANIFEST.json, the guest's decoders, and the tests that encode the versions, which the pull request explains under Changes to existing tests.
  • With the submodule at the new head, build OpenVMM with python3 scripts/nvx.py build-openvmm, and run python3 scripts/nvx.py test-microvm --backend BACKEND on each backend that you can reach, locally or through nvx-prepare-host; leave the others to CI.

Its body fills the pull request template, with an OpenVMM pin section that gives the OpenVMM source (the pinned revision, the previous pin, the new base, upstream main since it, the absence of an OpenVMM pull request, and the signatures), what changed in OpenVMM and in NVX, the equivalence evidence, and the landing order of section 7. Ask whether it is Draft or Ready.

A release completes no issue, so the Issue link check flags its pull request and creates the no-issue label when the repository lacks it. Then label the pull request no-issue, which exempts it, with gh pr edit P --repo microsoft/nvx --add-label no-issue. A pin that promotes an OpenVMM fix is not a release: it references the fix's issue instead.

7. Land The Release

Once OpenVMM CI passed NVX's required jobs on the new head, and only when the user asks:

python3 scripts/openvmm_release.py land --remote REMOTE --old-head OLD_HEAD --new-head NEW_HEAD --prev-release PREV_RELEASE --push

Without --push, it prints the plan. It fetches feature/microvm/dev again and stops when the branch moved: carry the new commits onto the release, repeat sections 4 to 6, including publication, OpenVMM CI, and the NVX pin, and land again with the new heads. It then fast-forwards the previous release branch to the old head, never by force, so that every revision of the old line that NVX pinned stays on a branch that git submodule update of an older NVX commit can fetch; and it moves feature/microvm/dev to the new head with a lease on the old one. Each OpenVMM pull request still open against feature/microvm/dev then needs a rebase. The NVX pull request merges through the merge queue once a maintainer approves it.

Report

Report the kind and version of the release; the old and new bases and heads; the drops with their upstream pull requests; the conflicts and their resolutions; the fixups or folds; the merge and signature checks; the equivalence evidence; the per-commit and head validation; the OpenVMM CI runs; the previous release branch's fast-forward and the move of feature/microvm/dev; the NVX commits, pull request, and exact-head workflow run; and every blocked or pending gate.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at fef56ac. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 7 hours ago.

Activeupdated 4 days ago
argument-hint
[rebase|reorganization] [upstream=main] [Draft|Ready]

README badge

README badge for microsoft/nvx/nvx-rebase-openvmm-chain