contributing

Contributing & Testing

How changes get into Launchstation: what to run before opening a pull request, what CI enforces, and what only real hardware can prove.

Workflow

1. Fork NathanNeurotic/Launchstation and branch from master. Check existing issues and open a draft early for anything large (storage-driver and IOP-lifecycle changes in particular).
2. Build locally with the LLVM toolchain. A change that only compiles with GCC is not releasable.
3. Run the affected tests, and the whole suite for anything touching shared code such as init.c, dash_worker.c or the file-copy path.
4. Update documentation in the same pull request (see below).
5. Open a pull request. CI runs on every push and pull request; only a verified push to master can publish the rolling release.

What CI enforces

.github/workflows/compile.yml (Automated-Build) runs, in order:

1. the explicit list of tests/test_*.py scripts, then the copy-test fixture generator;
2. the documentation site build (python3 docs-site/build.py);
3. SDK install, ps2build update and the LLVM toolchain check;
4. Mbed TLS and libjpeg-turbo builds, the Google client header, the isolated PC CARD CF driver;
5. the standard and DS34 builds, then check_ds34_build.py, check_toolchain_purity.py, check_udpfs_smap.py and check_loader_layout.sh;
6. packaging with package_apps.py and a second run of the package test; artifacts are uploaded.

On master pushes, a final step publishes the four packages to the rolling latest release only if the tests, both builds and every check passed, if master did not move during the build, and if the previous latest commit is an ancestor of the new one (the in-app updater relies on that lineage). It then re-downloads each published asset, compares it byte for byte, and only then moves the tag. Pull requests build review artifacts but never overwrite public downloads.

Writing and running tests

• Tests are standalone scripts: python3 tests/test_name.py exits non-zero on failure and normally prints a PASS: line.
• Prefer compiling the production source with small stubs (see test_worker_queue.py, test_copy_pipeline.py, test_pccf.py) over re-implementing logic in the test. The host compiler is gcc or clang.
• Source/workflow-contract tests (test_llvm_toolchain.py, test_rolling_release_workflow.py, test_native_cloud.py, test_self_update.py) read files and assert on them; update them deliberately when you change the contract they protect.
• Register new tests: CI runs an explicit list. Add a line to the first step of compile.yml; a test that is not listed does not gate merges.
• Run everything locally with for t in tests/test_*.py; do python3 "$t" || echo "FAIL $t"; done from inside a Git checkout.

Fixtures live in tests/fixtures and tests/pccf-stubs. Passing host tests do not establish console behavior: USB timing, IOP stalls, DEV9 sharing, display output and external-core handoffs need a console, and release notes say so.

Hardware validation

When you test on real hardware, report the console model and revision, video mode, boot device and exact ELF commit (shown by Tools > About Launchstation), the storage devices attached and the minimal reproduction steps. Say clearly what you did not test (for example one USB drive but not two). The copy-test fixture (LS-COPY-TEST.zip, produced by scripts/copy_test_pack.py and uploaded by CI as the Launchstation-copy-test artifact) gives deterministic files for verifying copies across devices; --verify checks a returned folder.

Documentation and attribution

• User documentation is docs-site/content/*.html plus docs-site/manifest.json; long-form guides are docs/wiki/*.md. Do not edit gh-pages or the GitHub wiki by hand; both are generated.
• Add a bullet to the ## Rolling section of CHANGELOG.md for user-visible changes. The rolling release notes are built from that section.
• Pages must match the code: when you change a menu label, file name, default or network behavior, grep docs-site/content, docs/ and README.md for it.
• Every external project you vendor, link or mention needs an entry in Credits and docs/THIRD_PARTY_CREDITS.md, with the role (vendored code, compiled dependency, external program, service, or reference) and the license. Keep original file-level notices intact. For vendored source also record upstream URL, base commit, local changes and license in an ORIGIN.md or VENDORED.md beside it (see iop/udpfs_smap/ORIGIN.md and iop/pccf/VENDORED.md).
• There is no root LICENSE file, and the tree contains components under different terms (AFL-2.0, AFL-3.0, MIT, BSD, Apache-2.0 and a restrictive legacy libcdvd license); do not assume one license applies to every file.

Repository hygiene

• Never commit generated or secret files: githash.h, .cloud-deps/, .jpeg-deps/, .cache/, build*/, .ps2-ds34.yaml, packages and ZIPs (they are in .gitignore), or Google client secrets, token files (WLE-CLOUD.TOK) and MagicGate keys (PS2KEYS.dat).
• The official Google OAuth client comes only from the repository secrets WLE_GOOGLE_CLIENT_ID and WLE_GOOGLE_CLIENT_SECRET; forks build without it.
• Keep changes behavior-neutral when refactoring, and keep new IOP modules lazy-loaded.

Reporting bugs

Use the Launchstation issue form. It asks for the console model, the build commit, the package you installed, the storage and network setup, and the display chain, so complete reports are triaged quickly. Consoles with a modchip installed are a confounder; confirmation on an unmodified console is appreciated. See also Good bug report.