Contributing
Thank you for your interest in bootc-migrate.
Note: this tool does an in-place migration of a real system. Treat changes to the migration phases (
src/migration/) with care. Run the end-to-end test suite before you merge changes.
Contribute compute — no code needed
Your machine runs one task at a time using your signed-in AI coding CLI. The relay alternates between eligible School (OS) and Reef (apps) hives after each task. If one hive has no work, the other can continue.
The guide covers prerequisites, verified just setup, credentials, provider
costs, and how to stop with Ctrl+C. Your subscription quota or API charges apply.
Never post account credentials or API keys in issues or pull requests.
Development setup
You need a stable Rust toolchain (edition 2024, rust-version = 1.88.0)
and just.
cargo build
just check # clippy + rustfmt + unit tests + shellcheck — run before every PR
IDE setup
Standard rust-analyzer works out of the box. The crate uses clippy with
extra lints (see Cargo.toml). Run just check instead of cargo clippy
to get the full lint set.
Running the end-to-end tests
The E2E harness boots a real QEMU VM, runs the full migration, reboots, and validates the result. It needs additional host packages:
# Fedora/RHEL
sudo dnf install qemu-system-x86_64 edk2-ovmf podman cryptsetup lvm2 swtpm
# Ubuntu/Debian
sudo apt install qemu-system-x86 ovmf podman cryptsetup-bin lvm2 swtpm
You also need root (for loop mounts and pflash) and outbound registry access
(ghcr.io) to pull the Bluefin/Dakota images. On a fresh machine, seed the
local registry cache first (saves ~8 GB of re-pulls on every run):
just registry-start # start a local OCI registry on localhost:5000
just registry-cache # pull Bluefin + Dakota; push to local registry
E2E scenarios
| Recipe | What it tests | Disk | Notes |
|---|---|---|---|
just e2e | Bluefin stable → Dakota (btrfs, x86_64) | 20 GB | Default; fastest |
just e2e-lts | Bluefin LTS → Dakota (XFS + ext4 loopback) | 20 GB | LTS base |
just e2e-luks | Bluefin LTS → Dakota (XFS + LUKS + swtpm) | 40 GB | Encrypted root |
just e2e-lvm | Bluefin LTS → Dakota (LVM-on-LUKS, separate /var) | 40 GB | Most complex |
just e2e-tui | Bluefin stable → Dakota, driven through the TUI wizard | 40 GB | E2E_MODE=tui-migrate |
The local recipes differ from the CI matrix.
For example, just e2e-lts uses XFS and a 20 GB disk to test the ext4
loopback store. The CI LTS cell uses ext4 and a 40 GB disk.
The CI matrix lives in .github/e2e-scenarios.yml, which is authoritative;
README.md reproduces it. Don't sync these two tables into one — they answer
different questions.
Run the default scenario:
just e2e
Watch progress in another terminal:
just watch # tails the latest .log; exits on errors or idle timeout
Or connect to the VM with SSH:
just e2e-ssh # opens an interactive SSH session to port 2222
Debugging a failed E2E run
just e2e-failures # grep log for failures/errors
just e2e-composefs # grep for composefs-related boot messages
just e2e-tail # tail the QEMU serial console (high-signal lines only)
just e2e-status # show disk.raw status + QEMU/SSH availability
To reproduce a failure after the migration without setup:
SKIP_SETUP=1 just e2e-reboot-test
Using Corral VMs for interactive testing
Corral provisions KubeVirt (or local QEMU) VMs from bootc container images. Corral is useful for interactive TUI tests when the scripted QEMU harness is too rigid.
Setup — install the corral binary (see Corral's README), then create a Bluefin VM:
$ corral create tui-e2e --image ghcr.io/projectbluefin/bluefin:stable \
--cpu 2 --memory 4Gi --disk 40Gi --efi
$ corral start tui-e2e
SSH into the VM:
corral ssh tui-e2e --user root
Deploy a local build to the VM (cross-compile or build on the VM):
# Option 1: Build on the VM (Rust must be installed in the VM)
tar czf /tmp/bmc-src.tar.gz --exclude=target --exclude=.git .
base64 /tmp/bmc-src.tar.gz | corral ssh tui-e2e --user root -c \
"base64 -d > /tmp/src.tar.gz && mkdir -p /tmp/bmc && \
tar xzf /tmp/src.tar.gz -C /tmp/bmc && cd /tmp/bmc && \
cargo build --release && \
cp target/release/bootc-migrate /usr/local/bin/"
# Option 2: If architectures match, just ship the binary
base64 target/release/bootc-migrate | corral ssh tui-e2e --user root -c \
"base64 -d > /usr/local/bin/bootc-migrate && \
chmod +x /usr/local/bin/bootc-migrate"
Capture TUI screenshots (the VM won't have tmux on an immutable OS, but Python3 is available for PTY capture):
corral ssh tui-e2e --user root -c "python3 << 'EOF'
import pty, os, time, select, re, struct, fcntl, termios, sys
rows, cols = 30, 100
pid, fd = pty.fork()
if pid == 0:
ws = struct.pack('HHHH', rows, cols, 0, 0)
fcntl.ioctl(sys.stdout.fileno(), termios.TIOCSWINSZ, ws)
os.environ['TERM'] = 'xterm-256color'
os.execvp('bootc-migrate', ['bootc-migrate'])
else:
ws = struct.pack('HHHH', rows, cols, 0, 0)
fcntl.ioctl(fd, termios.TIOCSWINSZ, ws)
time.sleep(2)
out = b''
while select.select([fd],[],[],1)[0]:
out += os.read(fd, 65536)
os.write(fd, b'q'); time.sleep(0.5)
os.write(fd, b'h'); time.sleep(0.3)
os.write(fd, b'\r'); time.sleep(0.5)
os.waitpid(pid, 0)
text = re.sub(r'\x1b\[[0-9;]*[a-zA-Z]', '', out.decode('utf-8', errors='replace'))
print(text)
EOF"
Corral VMs in CI — the CI matrix uses the scripted QEMU harness
(tests/run-e2e.sh) for reproducibility. Corral VMs are for developer
convenience only and are not required to contribute.
Cleaning up after E2E
just cleanup # kill QEMU, prune podman, remove disk.raw and .log files
Adding a new E2E scenario
- Add a new recipe in
justfilemodelled one2e-luksore2e-lvm. - Add the scenario to
.github/e2e-scenarios.yml. Setname,base,target,filesystem,disk_size, and any overrides. While the scenario is exploratory, addallow_failure: true. This keeps it out of the per-PR round-robin, so only the nightly run uses it. - Update the CI matrix table in AGENTS.md.
- Document the scenario in docs/filesystem-support.md.
Before you open a PR
just checkpasses (clippy + rustfmt + unit tests + shellcheck — this is what CI'svalidatejob runs).cargo deny checkpasses if you touched dependencies.- Commits follow the
component: Summaryformat in REVIEW.md. Squash fixups before merge. - Add unit tests for new logic (prefer table-driven tests, per REVIEW.md).
- Exercise migration-path changes with the default E2E scenario.
- If your change affects kernel args or boot artifacts, run the E2E matrix or wait for CI.
- The change satisfies the Definition of Done (REVIEW.md). Every claim matches the diff. All required checks pass on the head commit.
Code review
Read REVIEW.md. It describes the Definition of Done (DoD),
test requirements, and commit conventions. AI contributions must follow
AGENTS.md (no automatic Signed-off-by; add an Assisted-by: trailer,
and complete all validation steps).
Dependency update policy
Dependency updates come through Renovate (see
renovate.json). Renovate applies patch updates when CI passes.
Minor and major updates get a PR for human review. When you review Renovate PRs:
- Check the release notes for incompatible changes.
- Verify
cargo deny checkstill passes. - Run
just checklocally if the crate is a key dependency (rustix,clap,anyhow,serde_json).
License
By your contribution, you agree to dual-license your work under the MIT and Apache-2.0 licenses.