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 inopenvmm/itself.Use a remote of
openvmm/that resolves tomicrosoft/openvmm; add one withgit -C openvmm remote add REMOTE https://github.com/microsoft/openvmm.gitwhen none does, since older checkouts namenanvix/openvmmorigin.Record the state:
python3 scripts/openvmm_release.py state --remote REMOTE --kind rebaseIt fetches upstream
main,feature/microvm/dev, and the release branches; stops on a shallow history; and reportsold_head,old_base(which must be the roadmap's fork base), the previous release and its head, NVX's pin,new_baseand its date, the next version (refusing one that exists), the open OpenVMM pull requests intofeature/microvm/devwith their stacked layers, and NVX's open pin promotions. Pass--kind reorganizationfor 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/devwithgh pr editonly once its parent landed, aftergh stack unstackwhen 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.gitmodulestracks oncefeature/microvm/devmoves.
2. Choose What To Drop
python3 scripts/openvmm_release.py drops --old-base OLD_BASE --old-head OLD_HEAD --new-base NEW_BASEIt 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
Add the worktree with an absolute directory outside both checkouts, and replay the chain onto the new base, changing each dropped commit's
picktodrop:git -C openvmm worktree add -b microvm-release-VERSION DIRECTORY OLD_HEAD git -C DIRECTORY rebase -i --onto NEW_BASE OLD_BASEKeep commit signing on; never pass
--no-gpg-signor overridecommit.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.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 regeninstead of merging their text, and requirecargo xtask fmt --pass verify-floweyat every commit that changesflowey/or the generated files. - In
Cargo.lock, keep both sides' entries, and requirecargo check --lockedat that commit.
- Regenerate generated pipelines with
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.Check the chain:
python3 scripts/openvmm_release.py check-chain --dir DIRECTORY --new-base NEW_BASE --old-base OLD_BASE --old-head OLD_HEADIt 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_BASErunsrustfmton the changed Rust files,cargo check --locked --workspace --all-targets, andcargo xtask fmt --pass lintsat 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 warningson Linux and Windows, the packages' unit tests, and the microVM VMM tests throughcargo 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 --pushIt 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(orreorganized onto upstream main) anddoc: map the OpenVMM roadmap onto the microVM VERSION rebase(orreorganization). - The comparisons of what
nvxcopies 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 runpython3 scripts/nvx.py test-microvm --backend BACKENDon 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 --pushWithout --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.