# Contributing to Mactoy Thanks for helping. Mactoy writes raw bytes to disks as root, so the bar for changes is higher than usual in some places. This page explains where, and how to get a pull request merged without a lot of back and forth. ## Before you start - **Bugs:** open an issue first if you can. Include your macOS version, your Mactoy version, what you did, and what happened. For install or update failures, attach the output of: ```sh log show --predicate 'subsystem == "com.mactoy"' --last 1h ``` - **Features:** welcome. You don't need to ask first, just open a PR. If the change is large or reworks how something already works, an early issue or draft PR can save you time, but it's optional. - **Small fixes** (typos, docs, an obvious one-line bug) are welcome too. - **Security problems:** don't open a public issue. Follow [SECURITY.md](SECURITY.md). ## Building and testing You need macOS 13.5 or newer and Xcode 16+ (Swift 6). ```sh swift build swift test ``` `swift test` needs no root, touches no real disks and makes no network requests. Two tests are opt-in and skipped by default: `MACTOY_REAL_VTOYEFI_IMG` (converts a real Ventoy EFI image) and `MACTOY_NETWORK_TESTS` (downloads from GitHub). Their doc comments show how to run them. `./scripts/build-app.sh` builds `build/Mactoy.app` for running the UI. ### What your own build can and can't do The privileged helper (`mactoyd`) only accepts connections from an app signed with the maintainer's Developer ID. A build you make yourself will run and show the UI, including disk detection and Manage Disk, but it **cannot** install, update or flash a drive. To exercise the install and update code, use the end-to-end harness in [`scripts/e2e/`](scripts/e2e/README.md). It runs the real `VentoyDriver` against a disk image, needs no root, and boots the result in QEMU under UEFI and legacy BIOS. ## Pull requests - **One change per PR.** A bug fix and a refactor are two PRs. - **Branch from the latest `main`**, and rebase if `main` moves before review. - **Tests:** new behaviour and bug fixes need tests. Put pure logic in `MactoyKit` so it can be tested without the UI. Tests use Swift Testing (`import Testing`). - **Describe how you verified it.** Paste the `swift test` summary line, and say what you tried by hand (which macOS, which drive or disk image). - **Screenshots** for any UI change. - **Docs:** update `README.md` if you change something user-visible. Leave `CHANGELOG.md`, release notes and version numbers alone — the maintainer updates those when cutting a release. - **Keep the minimum at macOS 13.5.** Newer APIs need an `#available` check and a fallback. The `LiquidGlass.swift` wrappers show the pattern. ### Code - Match the style of the file you're in: naming, comment density, structure. - Comments should explain *why*, not *what*. Link the issue number when a change exists because of a report (`// issue #7`). - New third-party dependencies: call them out in the PR description and say why the standard library isn't enough. ### Matching Ventoy's behaviour Mactoy must produce drives that behave exactly as if Ventoy's own tools had made them. When your change touches how Ventoy reads the drive — the boot files, `ventoy.json`, where images are found — check Ventoy's source or docs and link what you relied on in the PR. "It works on my drive" isn't enough on its own. Useful starting points: - `INSTALL/tool/VentoyWorker.sh` and `ventoy_lib.sh` — what Ventoy2Disk writes - `GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/` — what the boot menu reads - — plugin and `ventoy.json` docs ## Areas that get extra scrutiny Changes to any of these are reviewed line by line and need tests that fail without the change: - `Sources/MactoyKit/VentoyDriver.swift`, `RawImageDriver.swift`, `DiskWriter.swift`, `GPT.swift`, `MBR.swift`, `VentoyLayout.swift`, `VentoyESP.swift`, `FAT16Reader.swift` — the bytes that get written. - `Sources/mactoyd/` — the root helper and its client check. - Disk selection and confirmation in `Sources/Mactoy/AppState.swift`. Mactoy has a six-layer defence against writing to the wrong disk (see the v0.3.1 entry in `CHANGELOG.md`). Don't remove or weaken any layer, even if it looks redundant. ## Adding a boot theme Mactoy's theme picker lists the themes in [`themes/catalog.json`](themes/catalog.json). The app reads that file from `main`, so once a theme PR is merged it appears for everyone without a new Mactoy release. Theme PRs are welcome, and they need a screenshot. 1. Find a fixed download of the theme: a release asset, or a commit archive (`https://codeload.github.com///zip/`). Branch archives change, so they aren't accepted. 2. Get its checksum and the folder that holds `theme.txt`: ```sh swift run --package-path scripts/themes mactoy-themes hash ``` 3. Add an entry to `themes/catalog.json`. Copy an existing entry, set `download.root` to the folder from step 2, and set `settings`: - `file` (usually `theme.txt`); - any `fonts` (`.pf2`) the theme needs; - `gfxmode` (`1920x1080,auto` unless the theme is designed for another size); - optionally `ventoy_left`, `ventoy_top`, `ventoy_color`. Set `showsVentoyHotkeys` to `false` for general GRUB themes that don't show Ventoy's F1–F6 bar. The `id` can't start with `custom-` (Mactoy names the themes people save on their own Mac that way) or be `ventoy-default`; `validate` rejects both. 4. Add a screenshot of the theme booted in Ventoy as `themes/previews/.jpg` (16:9, at least 1280 px wide, at most 600 KB). `scripts/themes/render-preview.sh ` makes one in QEMU (`brew install qemu`); a photo or capture from a real machine is fine too. (`themes/previews/ventoy-default.jpg` is the picture of Ventoy's own menu for the picker's "Ventoy default" tile. It isn't a theme, so leave it alone.) 5. Check it and regenerate the gallery and the preview credits: ```sh swift run --package-path scripts/themes mactoy-themes validate themes/catalog.json --download --only swift run --package-path scripts/themes mactoy-themes gallery themes/catalog.json themes/README.md swift run --package-path scripts/themes mactoy-themes credits themes/catalog.json themes/previews/CREDITS.md ``` 6. Try it on a Ventoy drive that is mounted on your Mac. The theme isn't on `main` yet, so install it from your local catalog: ```sh swift run --package-path scripts/themes mactoy-themes install themes/catalog.json /Volumes/ ``` This replaces the drive's current theme and removes any other theme folders Mactoy added to it. Use a spare stick or a Ventoy disk image, not a drive you rely on. 7. Open the PR with the theme template (add `?template=theme.md` to the new-PR URL) and paste the screenshot. CI runs `validate --download` on the whole catalog, `gallery --check` and `credits --check`, and the maintainer reviews the screenshot and the download before merging. What Mactoy copies to a drive: only `.txt`, `.png`, `.jpg`, `.jpeg`, `.tga` and `.pf2` files, never hidden files, at most 40 MB. It never copies `.cfg` files, because Ventoy runs `ventoy_grub.cfg` as a script at boot. The only settings Mactoy writes are the six `settings` keys above, and it changes nothing else in the user's `ventoy.json`. The default theme, Catppuccin Mocha, ships inside the app under `themes/bundled/`, so installing it needs no download. A PR that touches `themes/bundled/` gets extra scrutiny, because those bytes ship in the app. CI checks each bundled folder byte for byte against its pinned download. Folders there are made with `swift run --package-path scripts/themes mactoy-themes bundle themes/catalog.json themes/bundled`, never by hand, and a folder is only used while its name and marker match the catalog entry, so changing that entry means running `bundle` again. The licenses of what ships there sit beside the folders as `themes/bundled/LICENSE-*.txt` (Catppuccin's MIT license, and the SIL Open Font License for its Terminus font), not inside them, because CI compares each folder with its download byte for byte. Bundling another theme means adding its license there too. If you're only adding a theme to the picker, leave `themes/bundled/` alone. ## AI-assisted contributions These are welcome. Please say in the PR that you used an AI tool. You're responsible for what you submit, however it was written. That means testing it properly, not only checking that it compiles. You should be able to explain what the change does and how you verified it: which tests cover it, what you tried by hand, and what you checked it against. ## License By contributing, you agree that your contribution is licensed under the project's [MIT License](LICENSE).