Skip to content

Contributing

Contributions are welcome.

Development Setup

Clone the repository:

git clone https://github.com/basnijholt/zfs-encrypt-migrate
cd zfs-encrypt-migrate

Install development dependencies:

uv sync --dev

Running Tests

uv run pytest

The unit tests drive a simulated zfs, so they never touch a real pool. The NixOS VM test runs every command against real OpenZFS on loopback pools inside a VM (x86_64-linux, with KVM):

nix build .#checks.x86_64-linux.integration -L

Never point the CLI at real pools while developing: it renames and unmounts datasets.

Code Quality

Run linting:

uv run ruff check .
uv run ruff format --check .

Run type checking:

uv run mypy zfs_encrypt_migrate

Run Nix checks:

nix flake check --all-systems

Documentation

Install docs dependencies and build the site:

uv sync --group docs
uv run zensical build

The generated site is written to site/. GitHub Pages deploys that directory from the Documentation workflow on main.

The CLI help in README.md is generated; regenerate it after changing commands or options:

uvx --with . markdown-code-runner README.md

Project Structure

zfs_encrypt_migrate/              # Python package
zfs_encrypt_migrate/cli.py        # Typer command registration, shared options and exit codes
zfs_encrypt_migrate/migrate.py    # seed, catchup, cutover, the swap and the abort guard
zfs_encrypt_migrate/tree.py       # tree-seed, tree-move and tree-finish
zfs_encrypt_migrate/audit.py      # Unencrypted-dataset audit
zfs_encrypt_migrate/zfs.py        # zfs/zpool wrapper and dataset-name validation
zfs_encrypt_migrate/process.py    # Command runner and the send | recv pipeline
zfs_encrypt_migrate/sizes.py      # --min-free size parsing
nix/nixos-module.nix              # NixOS module with the audit service and timer
nix/integration-test.nix          # NixOS VM test against real OpenZFS
tests/                            # Unit, CLI, packaging, workflow and NixOS module tests
docs/                             # Zensical documentation site

Release Checklist

  1. Update VERSION.
  2. Open and merge a PR.
  3. Publish a GitHub release tagged vX.Y.Z, where X.Y.Z exactly matches VERSION.
  4. Confirm the Upload Python Package workflow publishes to PyPI.

License

By contributing, you agree that your contributions will be licensed under the MIT License.