From 380f55e1cd9f97b890494748cd1bf6becbb243ff Mon Sep 17 00:00:00 2001 From: unicxrn Date: Sat, 10 Oct 2026 23:05:35 +0200 Subject: [PATCH] Simplify contributing guide --- .github/workflows/release.yml | 2 + CONTRIBUTING.md | 107 +++++++++++----------------------- src-tauri/tauri.conf.json | 2 +- 3 files changed, 38 insertions(+), 73 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 703862f..8b0813b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -72,6 +72,8 @@ jobs: TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }} TAURI_SIGNING_PRIVATE_KEY_PASSWORD: "" with: + # Update files are only made (and signed) for official releases. + args: --config '{"bundle":{"createUpdaterArtifacts":true}}' includeUpdaterJson: true updaterJsonPreferNsis: true tagName: ${{ github.ref_name }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 50cc40c..c8a533a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,90 +1,53 @@ -# Contributing +# Contributing to Prospack -## Layout +Thanks for helping out. Bug reports, fixes and new ideas are all welcome. -| Path | What | -| --- | --- | -| `src/` | The app UI (Svelte 5). `src/lib/mock.js` simulates the backend so `npm run dev` works in a browser. | -| `src-tauri/src/` | The Rust backend: `pipeline.rs` (the job queue), `engine.rs`, `ftp.rs`, `ps5.rs`, `discover.rs`, `dump.rs`, `settings.rs`. | -| `engine/` | The Python engine: MkPFS plus the deep verifier, frozen into `prospack-engine` by `build.py`. | -| `installer/` | "Prospack Setup", the Windows installer app. It embeds the NSIS installer and runs it silently. | -| `tests/fake_ps5.py` | A fake PS5 FTP server (with ftpsrv's quirks) and a fake ShadowMountPlus, for end-to-end tests. | +## Reporting a bug -## Development +Open an issue and include: + +- what you did and what happened instead +- your OS, your Prospack version and your ShadowMountPlus version +- the game's activity log from the app, if the problem happened during a job + +## Setting up + +You need Node 22, Rust and Python 3.12. ```bash npm install -python3 -m venv .venv && .venv/bin/pip install -r engine/requirements-build.txt pyftpdlib -.venv/bin/python engine/build.py # needed once: Tauri expects the sidecar to exist +pip install -r engine/requirements-build.txt +python engine/build.py # builds the compression engine the app runs npm run tauri dev ``` -To work on the UI only, run `npm run dev` and open http://localhost:1430. Add `?setup` to -the URL to see the first-run wizard. +If you only want to work on the interface, `npm run dev` opens it in a browser with a +simulated PS5. Add `?setup` to the URL to see the setup wizard. -Engine lookup order: -1. `prospack-engine` next to the app executable (release builds). -2. `$PROSPACK_ENGINE`. -3. A developer venv in the app data folder, which runs `engine/prospack_engine.py`. +## Where things are + +| Path | What it holds | +| --- | --- | +| `src/` | The interface (Svelte) | +| `src-tauri/src/` | The app backend (Rust): the job queue, FTP, PS5 checks | +| `engine/` | The compression engine (Python, using MkPFS) | +| `installer/` | Prospack Setup, the Windows installer app | +| `tests/fake_ps5.py` | A fake PS5 used by the tests | ## Tests ```bash -cd src-tauri -cargo test # unit tests +cd src-tauri && cargo test ``` -The end-to-end tests run the whole pipeline (compress, verify, upload, mount) against the -fake PS5. They never touch a real console. They need a scratch folder containing: +The end-to-end tests run a whole job against the fake PS5, never a real console. CI runs +them on Linux and Windows for every pull request, so you don't have to set them up +yourself. If you want to run them locally, see the steps in `.github/workflows/ci.yml`. -- `mkvenv/`: a venv with `engine/requirements.txt` and `pyftpdlib`; -- `fake_ps5.py`: copied from `tests/`; -- `fakedump/PPSA00001-app`: from `python engine/make_fake_dump.py /fakedump/PPSA00001-app`. +## Pull requests -```bash -PROSPACK_E2E_SCRATCH= PROSPACK_ENGINE=$PWD/binaries/prospack-engine- cargo test -- --include-ignored -``` - -The scenarios covered are: -- a full run; -- an identical re-upload being skipped; -- a tampered image blocked at Verify; -- "Compress again"; -- resuming an interrupted upload; -- Cancel killing the engine; -- the wizard's checks. - -`discover_lan` (also ignored) prints the FTP servers on your real network. It's read-only. - -## Things the PS5 does differently - -The PS5's usual FTP server, ftpsrv 1.6.x, differs from standard FTP in ways the code relies on: - -- RNTO, DELE and MKD reply **226** instead of 250/257. -- `SIZE` on a missing file returns `213 18446744073709551615` (-1), so existence is checked with `LIST`. -- STOR doesn't truncate before writing, so temporary files are deleted before they're rewritten. - -The ShadowMountPlus details: -- It ignores dot-files, which is why uploads use `..ffpfsc.prospack-part`. -- It only reliably notices a new image when `manual.lst` changes. - -## Updates and signing - -Prospack updates itself with Tauri's updater. It reads `latest.json` from the latest -published GitHub release and only installs files signed with the project's private key. -The public key is in `src-tauri/tauri.conf.json`. - -- `npm run tauri dev` and `npx tauri build --no-bundle` don't need the key. -- A full `npx tauri build` makes update files, so it needs the key in the environment: - `TAURI_SIGNING_PRIVATE_KEY="$(cat ~/.tauri/prospack.key)"`. If you don't have the key, - add `--config '{"bundle":{"createUpdaterArtifacts":false}}'` to build without update files. -- The release workflow reads the key from the `TAURI_SIGNING_PRIVATE_KEY` repository secret. -- A `.deb` install can't replace itself. Those users are pointed at the release page instead. - -## Releases - -Bump the version in `package.json`, `src-tauri/Cargo.toml` and `src-tauri/tauri.conf.json`, -then push a tag such as `v0.1.0`. `.github/workflows/release.yml` builds Linux and Windows, -runs the tests (including the end-to-end tests with the frozen engine), builds Prospack -Setup, smoke-tests an unattended install and uninstall on Windows, and creates a **draft** -release for you to check and publish. +- Keep each pull request to one change, and say what it fixes or adds. +- Make sure `cargo test` and `npm run build` pass. +- Check how your change behaves on the PS5's FTP server, ftpsrv. It doesn't behave like a + standard one: some commands reply with different codes, `SIZE` returns -1 for missing + files, and uploads don't truncate existing files. `src-tauri/src/ftp.rs` handles these. diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json index 09a846d..1656179 100644 --- a/src-tauri/tauri.conf.json +++ b/src-tauri/tauri.conf.json @@ -62,7 +62,7 @@ } }, "category": "Utility", - "createUpdaterArtifacts": true + "createUpdaterArtifacts": false }, "mainBinaryName": "prospack", "plugins": {