Contributing

Contributions are welcome. This page covers the essentials. The full policy is in CONTRIBUTING.md.

Before you start

• Search the existing issues to avoid duplicate work.
• For a substantial change, open an issue first so the maintainers can confirm the direction.
• Keep each pull request focused on one change.

Set up

git clone https://github.com/vindeckyy/OpenBoxGL.git
cd OpenBoxGL
python3 web_app.py

Use Python 3.10 or newer. On Windows, run python web_app.py. On macOS, install a current Python, for example with brew install python@3.12.

To build the native window on Linux, run make native-host, then ./openbox-native.sh. On Windows, run scripts\build_native_host_windows.ps1. It needs the MSVC build tools and cmake on the PATH. On macOS, run scripts/build_native_host_macos.sh.

Run the tests

Command	Use it for
./run_all_tests.sh	The test suite, without coverage
make test-one TEST=tests/test_catalog.py	One test module
make check	The full gate, on Linux: lint, contract checks, the suite under coverage, and token hygiene
python scripts\run_windows_tests.py	The test suite on Windows

Coverage floors only go up. A change must keep the changed-line coverage gate green.

Where code goes

• New HTTP handlers go in handlers/, one module per domain. Shared helpers go in handlers/_shared.py.
• Platform-specific behavior goes in pkg/platform_compat.py, the only platform seam.
• Parity code goes in pkg/parity/.
• A new runtime module goes in runtime_modules.txt, with a matching test_*.py file.
• Colors, spacing, and type come from tokens in static/app.css :root. Themes override tokens only.
• A change to web_app.py needs a test that exercises the route it touches.

The full placement rules are in AGENTS.md.

Ground rules

• The runtime uses only the Python standard library. Avoid new dependencies, and get approval in the pull request before adding one.
• The project adds no telemetry.
• Do not commit ROMs, BIOS images, API tokens, or personal library data.
• Sign off every commit with git commit -s. The project uses the Developer Certificate of Origin.

Pull requests

1. Fork the repository, then create a feature branch from master.
2. Make clear commits. Run make check. If coverage tooling is missing, run ./run_all_tests.sh.
3. Open the pull request with the template. Describe the problem, the solution, and the test plan.

Commit messages

Write concise messages in the imperative mood. Recent history uses conventional prefixes with a module scope, such as fix(tests): and docs(1.19.1):.

Documentation

Engineering documents live in docs/. User documentation lives in the OpenBoxGL Pages repository, so changes to the documentation site go there.