Skip to main content

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​

Donate time with your AI CLI.

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​

RecipeWhat it testsDiskNotes
just e2eBluefin stable → Dakota (btrfs, x86_64)20 GBDefault; fastest
just e2e-ltsBluefin LTS → Dakota (XFS + ext4 loopback)20 GBLTS base
just e2e-luksBluefin LTS → Dakota (XFS + LUKS + swtpm)40 GBEncrypted root
just e2e-lvmBluefin LTS → Dakota (LVM-on-LUKS, separate /var)40 GBMost complex
just e2e-tuiBluefin stable → Dakota, driven through the TUI wizard40 GBE2E_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​

  1. Add a new recipe in justfile modelled on e2e-luks or e2e-lvm.
  2. Add the scenario to .github/e2e-scenarios.yml. Set name, base, target, filesystem, disk_size, and any overrides. While the scenario is exploratory, add allow_failure: true. This keeps it out of the per-PR round-robin, so only the nightly run uses it.
  3. Update the CI matrix table in AGENTS.md.
  4. Document the scenario in docs/filesystem-support.md.

Before you open a PR​

  • just check passes (clippy + rustfmt + unit tests + shellcheck — this is what CI's validate job runs).
  • cargo deny check passes if you touched dependencies.
  • Commits follow the component: Summary format 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 check still passes.
  • Run just check locally 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.