Skip to content
251 changes: 144 additions & 107 deletions BUILDING.md

Large diffs are not rendered by default.

151 changes: 93 additions & 58 deletions COMPATIBILITY.md

Large diffs are not rendered by default.

123 changes: 64 additions & 59 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,30 +1,31 @@
# Contributing to WrongGPU

WrongGPU is a community project: anyone can propose changes by pull request. It is also a clean-room implementation
(see [docs/CLEAN-ROOM.md](docs/CLEAN-ROOM.md)), and that only holds if every contribution is clean too. Please read
this whole page before you open a pull request. Ideas and plans: [ROADMAP.md](ROADMAP.md). Game results:
[COMPATIBILITY.md](COMPATIBILITY.md). New here? Read the [welcome discussion](https://github.com/phantoslayer21/wronggpu/discussions/1);
a good first task is [building from a fresh clone](https://github.com/phantoslayer21/wronggpu/issues/2).
WrongGPU is a community project and a clean-room implementation. Every contribution must follow the rules in
[docs/CLEAN-ROOM.md](docs/CLEAN-ROOM.md). Read this page before opening a pull request.

Start with the [welcome discussion](https://github.com/phantoslayer21/wronggpu/discussions/1). You can propose a change
from [ROADMAP.md](ROADMAP.md), report a game through [COMPATIBILITY.md](COMPATIBILITY.md), or help with
[building from a fresh clone](https://github.com/phantoslayer21/wronggpu/issues/2).

## How a pull request gets merged

1. You open a pull request against `main`, with the clean-room statement (first pull request) and every commit signed
off (see below). The pull-request template has checkboxes for both.
2. **CI** runs on a Windows runner (`.github/workflows/ci.yml`); it must pass:
- licence check: [REUSE](https://reuse.software) lint (the licence and copyright data in `REUSE.toml` is valid and
covers every file);
- line endings: files are stored exactly as committed (`.gitattributes` is `* -text`; no CR LF);
- CPU builds and tests: the converter, the shared settings, the FSR front end, the launcher core and the Ray
Reconstruction plugin with their CPU tests, and the CPU Python test set (`tools/ci/run_python_tests.py`).
CI has no GPU: kernels and the runtime library are not built there, and no GPU test runs.
3. **Checks by a maintainer, by hand, before merge:**
- **Clean-room gate:** every pull request is scanned on the maintainer's side before it is merged (a private scan
for material that must not appear in a clean implementation), and the clean-room statement is checked.
- **Review** by someone who did not write the change.
- **A GPU test on real hardware** (a Radeon RX 9000-series card) when the change touches kernels, the runtime,
the front end or the Ray Reconstruction plugin.
4. The project owner merges. Releases are built, tested on real hardware and published by the owner (see
[RELEASING.md](RELEASING.md)).
1. Open a pull request against `main`. Include the clean-room statement in your first pull request and sign off every
commit. The pull-request template has checkboxes for both.
2. Wait for CI on the Windows runner defined in `.github/workflows/ci.yml`. It must pass these checks:
- [REUSE](https://reuse.software) lint validates the licence and copyright data in `REUSE.toml` and checks that it covers every file.
- The line-ending check preserves files exactly as committed. `.gitattributes` sets `* -text` and forbids CR LF.
- CPU builds and tests cover the converter, shared settings, FSR front end, launcher core, and Ray Reconstruction
plugin. CI also runs the CPU Python tests through `tools/ci/run_python_tests.py`.

CI has no GPU. It does not build kernels or the runtime library, and it runs no GPU tests.
3. Wait for the maintainer's manual checks:
- Before every merge, the maintainer privately scans the pull request for material that must not appear in a clean
implementation and checks the clean-room statement.
- Someone who did not write the change reviews it.
- A change to kernels, the runtime, the front end, or the Ray Reconstruction plugin needs a test on a Radeon RX
9000-series card.
4. The project owner merges the pull request. Only the owner builds, tests on real hardware, and publishes official
releases. See [RELEASING.md](RELEASING.md).

## The clean-room statement

Expand All @@ -44,49 +45,53 @@ own PC are still very welcome.

## Sign-off (Developer Certificate of Origin)

Every commit carries a sign-off line, which certifies the [Developer Certificate of Origin 1.1](https://developercertificate.org/):
Sign off every commit to certify the [Developer Certificate of Origin 1.1](https://developercertificate.org/):

```
```text
Signed-off-by: Your Name <you@example.com>
```

`git commit -s` adds it. Pull requests with commits that are not signed off are not merged.
Use `git commit -s` to add the line. Pull requests with commits that are not signed off are not merged.

## What you may use

- Public documentation: AMD's RDNA 4 ISA and WMMA documentation, HIP / ROCm documentation and headers, LLVM AMDGPU
documentation, Microsoft's Direct3D 12 / DXIL / Win32 documentation, AMD's public FidelityFX API, papers and
- Public documentation: AMD's RDNA 4 ISA and WMMA documentation, HIP and ROCm documentation and headers, LLVM AMDGPU
documentation, Microsoft's Direct3D 12, DXIL, and Win32 documentation, AMD's public FidelityFX API, papers, and
general literature.
- Your own measurements on your own hardware with synthetic data.
- Third-party code only under one of these licences: MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, zlib, ISC, Boost
(BSL-1.0). Nothing under GPL, LGPL, AGPL or a licence without the right to redistribute in source and binary form;
nothing that forbids reverse engineering. Code that ends up in a shipped binary needs a maintainer's approval first.
List every new component in [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES) and in `REUSE.toml`.

Never add: files of the original upscaler of any kind (DLLs, headers, model data), model weights or data derived from
them, game files, screenshots or frame captures from games, or binaries.

## Every change

- An SPDX licence line for MIT (`SPDX-License-Identifier` followed by `MIT`, as at the top of every source file) in
every new source file; files that cannot carry one, such as JSON, are covered in `REUSE.toml`. The `**` rule in
`REUSE.toml` already covers every file, so CI's REUSE lint passes without a header: a missing header is caught in
review, not by CI.
- In the pull request, say for each new or substantially changed file what it is based on (public document, test
result or own design).
- Tests with synthetic data for what you change; the CPU tests pass (CI runs them; locally: [BUILDING.md](BUILDING.md)).
- No absolute paths of your PC, user names or machine names in code, scripts or documents. Tools are found through the
environment variables in BUILDING.md.
- Kernels: if a change is meant to keep the output bit-identical, say so and show the comparison (BUILDING.md, section
6).
- Numbers in documents (timings, quality figures): only with the measurement they come from (game, resolution, mode,
build, the log or result file). No number without its record.

## Bug reports and game reports

Use the issue templates: **Bug report** for problems (label `bug`), **Game compatibility report** for how a game
behaves (label `game-compatibility`) (see
[COMPATIBILITY.md](COMPATIBILITY.md), "How to add your game"). For a visual problem: the game, the scene, your settings,
your GPU and driver, and the zip from the launcher's **Collect logs** (check it first: it can contain your Windows user
name). Please do not attach the upscaler's DLLs or other copyrighted game files. Questions and discussion: the
[WrongGPU Discord server](https://discord.gg/745z9MfKwm).
- Third-party code under MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, zlib, ISC, or Boost (BSL-1.0). Do not use code
under GPL, LGPL, AGPL, or a licence that does not allow source and binary redistribution. Do not use code whose
licence forbids reverse engineering. Get a maintainer's approval before adding code that ends up in a shipped
binary. List every new component in [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES) and `REUSE.toml`.

Never add files from the original upscaler, including DLLs, headers, and model data. Never add model weights, data
derived from them, game files, game screenshots, game frame captures, or binaries.

## What every change needs

- Add an MIT SPDX licence line to every new source file. Use `SPDX-License-Identifier` followed by `MIT`, as in the
existing source files. Cover files that cannot carry a header, such as JSON, in `REUSE.toml`. The `**` rule in
`REUSE.toml` already covers every file, so REUSE lint passes without a header. Reviewers catch a missing header
instead.
- In the pull request, identify the basis of each new or substantially changed file. Name the public document, test
result, or your own design.
- Add tests with synthetic data for the changed behavior. Run the CPU tests locally with
[BUILDING.md](BUILDING.md#6-tests-cpu). CI runs the same tests.
- Keep absolute local paths, user names, and machine names out of code, scripts, and documents. Use the environment
variables in [BUILDING.md](BUILDING.md#2-where-the-build-finds-the-tools) to find tools.
- If a kernel change should keep the output bit-identical, say so and show the comparison described in
[BUILDING.md](BUILDING.md#comparing-kernels-with-a-release).
- Attach every timing or quality figure in a document to its measurement record. Include the game, resolution, mode,
build, and log or result file. Do not publish a number without its record.

## Report bugs and game results

Use the **Bug report** issue template for problems and the **Game compatibility report** template for game behavior.
They add the `bug` and `game-compatibility` labels respectively. See
[How to add your game](COMPATIBILITY.md#how-to-add-your-game) for the game-testing process.

For a visual problem, include the game, scene, settings, GPU, driver, and the zip from the launcher's **Collect logs**.
Check the zip before sharing it because it can contain your Windows user name. Do not attach the upscaler's DLLs or
other copyrighted game files.

Use the [WrongGPU Discord server](https://discord.gg/745z9MfKwm) for questions and discussion.
Loading
Loading