From 72d2f4519562b1c2b5dade5a75be70a4ae1e0048 Mon Sep 17 00:00:00 2001 From: NullMoth Systems Date: Fri, 13 Nov 2026 15:38:49 -0800 Subject: [PATCH] Developer kit: setup guide, tests on every pull request, issue templates, sign-off DEVELOPING.md covers what each part needs, the repository map, the unit tests, the hardware corpus and self-tests, building the Windows and Mac apps, testing on real hardware, the rules for changes, and where to start. The new Tests workflow runs the unit tests on every pull request and on main. Issue templates ask for the report ID and the machine. CONTRIBUTING.md asks for signed-off commits (Developer Certificate of Origin). The Mac app did not build with Swift 6.4: an unowned capture of self inside a closure that captured self implicitly is now an error under -warnings-as-errors. The outer closure now captures self explicitly, which keeps the same ownership as before. --- .github/CODEOWNERS | 1 + .github/ISSUE_TEMPLATE/bug.yml | 22 +++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/hardware.yml | 27 ++++++ .github/workflows/tests.yml | 29 ++++++ CONTRIBUTING.md | 4 + DEVELOPING.md | 134 ++++++++++++++++++++++++++++ mac/Sources/main.swift | 2 +- 8 files changed, 219 insertions(+), 1 deletion(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/hardware.yml create mode 100644 .github/workflows/tests.yml create mode 100644 DEVELOPING.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..fc6a1518 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @nullmoth diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 00000000..61620cd4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,22 @@ +name: Something went wrong +description: 1401 or the Mac app failed, or did something you did not expect. +body: + - type: input + id: report + attributes: + label: Report ID + description: Press Send logs in 1401 (Windows) or the 1401 Mac app and paste the ID it gives you, like NM-ABCD1234. + validations: + required: true + - type: textarea + id: what + attributes: + label: What happened + description: In a few sentences of your own, what you did, what you expected, and what you saw instead. + validations: + required: true + - type: input + id: machine + attributes: + label: Your PC + description: Board or laptop model, CPU and GPU. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..0086358d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: true diff --git a/.github/ISSUE_TEMPLATE/hardware.yml b/.github/ISSUE_TEMPLATE/hardware.yml new file mode 100644 index 00000000..90c23a63 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/hardware.yml @@ -0,0 +1,27 @@ +name: My hardware is not supported +description: 1401 refuses or mishandles a CPU, GPU, board or laptop. +body: + - type: input + id: report + attributes: + label: Report ID + description: From Send logs in 1401, if it got that far. + - type: input + id: machine + attributes: + label: Your PC + description: Board or laptop model, CPU, GPU, and Wi-Fi card if you know it. + validations: + required: true + - type: textarea + id: what + attributes: + label: What 1401 did + description: Which step stopped, and what it said. + validations: + required: true + - type: textarea + id: known + attributes: + label: Known to work elsewhere + description: Links to a working OpenCore setup or driver for this hardware, if you know one. diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 00000000..f5544c65 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,29 @@ +name: Tests + +on: + pull_request: + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: read + +jobs: + unit: + runs-on: macos-15 + timeout-minutes: 20 + env: + PYTHONDONTWRITEBYTECODE: '1' + steps: + - name: Check out the change + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 + with: + persist-credentials: false + # Full history: some tests compare against an earlier commit as their negative control. + fetch-depth: 0 + - name: Show the Python in use + run: python3 --version + - name: Unit tests + run: python3 -m unittest discover -s tests -t . -p 'test_*.py' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 104bd872..8dea5788 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,3 +17,7 @@ descriptions and bug reports are closed without review. - One change per pull request, and say what you tested: your PC, the stick, what you ran and what it printed. - Keep the description short: what was wrong, what you changed, how you tested it. Link the issue. - Run the tests before you open it: `python3 -m unittest discover -s tests -t . -p 'test_*.py'`. +- Sign off every commit (`git commit -s`). It certifies you wrote the change or may submit it under this + repository's licence (Developer Certificate of Origin, ). + +Setting up, the repository map, the full tests and the rules for changes are in `DEVELOPING.md`. diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 00000000..1f7b46ff --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,134 @@ +# Developing 1401 + +This is the guide for working on 1401's source. To report a bug, see `CONTRIBUTING.md`. + +## How changes get in + +1401 has one maintainer, who reviews and merges every change. You work in your own fork and send a pull request to +`main`; nothing lands without review. A small pull request with a clear test is merged much faster than a big one. + +1. Fork the repository and clone your fork with full history (`git clone` without `--depth`): some tests compare + against an earlier commit and fail on a shallow clone. +2. Make one change on its own branch. +3. Run the tests (below). They must pass on your machine before you open the pull request. +4. Sign off every commit (`git commit -s`, see "Sign-off" below) and open the pull request with the template filled in. + +## What you need + +| Part | Folder | Runs on | Needs | +|---|---|---|---| +| Engine (scan, build, BIOS guide, stick writer) | `p1401/` | any OS for the tests; Windows in the app | Python 3.12 or newer | +| Windows app (the window) | `windows/App/` | Windows | .NET SDK 8.0.425 (`global.json` pins it), Visual Studio C++ tools for `native/` | +| Mac app (after the install) | `mac/` | macOS 15 or newer | Xcode (Swift 6.3 and 6.4 both build it) | +| UEFI loader (experimental, unused by the app) | `loader/` | QEMU | Rust | +| Upstream engines (pinned copies) | `upstream/` | | do not edit; `PINNED.json` names the commits | + +Most work is in the engine, and the engine's tests need no special hardware. + +## Repository map + +- `p1401/`: the engine. Each step the window runs is a module: `scan.py` (Check this PC), `engine.py` and + `nullmoth.py` (Build the Mac setup and its rules), `guide.py` (Your BIOS steps), `usbwriter.py` (Create the macOS + stick), `report.py` (Send logs). `community_gpu.py` lists other people's GPU drivers and when to mention them. +- `windows/App/`: the C# window. It runs each engine step as `python -u -m ` and shows its output. +- `mac/`: the Mac app that finishes the setup after macOS is installed. `mac/build.sh` builds it and runs its own tests. +- `tests/`: unit tests (`test_*.py`), the hardware corpus (`tests/corpus/`), and the corpus runner (`run_corpus.py`). +- `tools/`: release, packaging and corpus tools. +- `docs/HOW-IT-WORKS.md`: what each step does, in order. Read it before changing a step. + +## Tests + +### Unit tests: no hardware, about 40 seconds + +```bash +python3 -m unittest discover -s tests -t . -p 'test_*.py' +``` + +A few tests are skipped outside Windows or without optional downloads; the skip message says why. These run on every +pull request. + +### The hardware corpus: real machines, offline + +The corpus is a set of public Hardware Sniffer reports from real PCs. Building all of them checks that a change to +the rules does not break a machine that worked before. + +```bash +python3 tests/corpus/fetch.py # download the reports, pinned by commit +python3 tests/run_corpus.py build # build every machine, apply the rules, run ocvalidate +``` + +The fetch and build take about three minutes and about 300 MB in `out/`, and need internet access (the engine +downloads OpenCore and the kexts it picks). Then the engine's own self-tests, which read the built corpus: + +```bash +python3 -m p1401.guide --selftest && python3 -m p1401.apple --selftest && python3 -m p1401.usbwriter --selftest \ + && python3 -m p1401.scan --selftest && python3 -m p1401.nullmoth --selftest +``` + +A self-test that says "can't run" is missing the corpus; fetch and build it first. `python3 -m p1401.selftest` is +behind the engine and fails today (its fake downloads predate the ZIP check in `p1401/archive_download.py`, and two +later arms no longer match the engine); bringing it up to date is an open task. Run the corpus whenever you change +a rule, a kext choice or anything in `p1401/engine.py` or `p1401/nullmoth.py`, and say in the pull request that it +passed. + +## Building + +**Windows app:** + +```powershell +dotnet build windows/App/App.csproj --configuration Release --output build +``` + +`.github/workflows/windows-candidate.yml` is the full packaging run, step by step. + +**Mac app:** + +```bash +bash mac/build.sh /tmp/1401-mac +``` + +It builds and runs the app's own tests first, then the app, in under a minute. `mac/Resources/NullMothSafe.efi` is +checked in; rebuild it only if you change `mac/efi-safe/` (rustup's `x86_64-unknown-uefi` target, then +`cargo build --release --target x86_64-unknown-uefi` in that folder, and copy `nullmoth-safe.efi` over it). The build stops with a `STOP:` line naming the test that failed. Its output is ad-hoc signed and is for testing only; +releases are built and signed by the maintainer. + +## Testing on real hardware + +- **Writing a stick erases it.** Use a spare stick with nothing on it, and check the disk number 1401 shows before you + confirm. +- Never test a change on a machine whose data you cannot lose. A wrong boot setting can leave a PC unable to start + until the BIOS is reset. +- Say in the pull request exactly what you ran it on: the board or laptop model, CPU, GPU, and what you saw. + +## Rules for changes + +- **No Apple code.** Nothing written by Apple goes into this repository: no binaries, no files copied from macOS or + its installers, and nothing generated from Apple's SDK headers. 1401 downloads what it needs from the original + source on the user's machine. +- **Other people's code keeps its licence.** If you add or update third-party code, say where it comes from, pin the + exact version, and add it to `NOTICE.md` and `p1401/licenses.json`. Code with no licence cannot be added; it can only + be linked so the user downloads it from its author. +- **Downloads are pinned.** Anything 1401 downloads names its exact URL, size and SHA-256, and the engine refuses a + file that does not match. +- **No secrets, keys or personal data** in code, tests or fixtures. Hardware reports in the corpus are public ones. +- **Fail loud.** If a step cannot do what it says, it stops and tells the user why. It never carries on as if it had + worked. +- Keep comments plain: explain why the code does what it does. + +## Sign-off + +Every commit must be signed off: `git commit -s` adds a `Signed-off-by:` line with your name and email. It certifies +that you wrote the change, or have the right to submit it, under this repository's licence, as set out in the +Developer Certificate of Origin (). Pull requests with unsigned commits cannot be +merged. + +## Where to start + +Issues labelled `help wanted` are open for anyone. Good first areas: + +- A machine that fails to build: add its public Hardware Sniffer report to the corpus and fix the rule it breaks. +- The BIOS guide (`p1401/guide.py`): missing or wrong steps for a board or laptop you own. +- Bring `p1401/selftest.py` back up to date with the engine (see Tests above). +- Community GPU drivers (`p1401/community_gpu.py`): a driver that is missing, or one whose release has moved on. + +Ask in the issue before starting something large, so two people do not build the same thing. diff --git a/mac/Sources/main.swift b/mac/Sources/main.swift index 6494922d..681829c5 100644 --- a/mac/Sources/main.swift +++ b/mac/Sources/main.swift @@ -995,7 +995,7 @@ final class App: NSObject, NSApplicationDelegate, WKScriptMessageHandler, WKUIDe alert.addButton(withTitle: "Download Driver") alert.addButton(withTitle: "Choose Driver File…") alert.addButton(withTitle: "Cancel") - alert.beginSheetModal(for: window) { response in + alert.beginSheetModal(for: window) { [self] response in DispatchQueue.main.asyncAfter(deadline: .now() + 0.3) { [unowned self] in switch response { case .alertFirstButtonReturn: