Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
87 lines (63 loc) · 3.73 KB

CONTRIBUTING.md

File metadata and controls

87 lines (63 loc) · 3.73 KB
Raw

Contributing

The most useful contribution is a hardware report

The compatibility table in the README currently rests on one verified cooler. Everything else is inference from a shared ODM. Reports are what turn those rows into facts — and a report that OpenDS360 did not work is worth as much as one that it did.

Open a hardware report →

Working on the code

git clone https://github.com/kitepon/OpenDS360.git
cd OpenDS360
dotnet build src/OpenDS360

Requires the .NET 8 SDK and Windows. The project targets net8.0-windows and uses WinForms, so it does not build elsewhere.

Two things about this repository cost people time if they are not said up front:

  • The build output is under a win-x64 subfolder, because a RuntimeIdentifier is set. bin/Debug/net8.0-windows/OpenDS360.exe may exist as a leftover from an earlier build and will not be the file you just built.
  • Stop the running app before building. It runs elevated and holds a lock on its own executable. dotnet build can report 0 errors while updating nothing.

Rules that protect the hardware

These are not style preferences. Breaking one can leave someone's cooler unusable.

Rule Why
Never send to report IDs 0xF0 / 0xF1 Presumed firmware update channel. A wrong write could brick the device
Clamp display values to 0–199 Sending 200 or more makes the display show 99
Never interrupt the 0.5 s send loop A watchdog blanks the display when the stream stops
Do not brute-force unknown commands Staying inside the parameters of the known 0x20 command is proven safe; nothing else is
Match the product string, not just VID/PID 0x2E3C belongs to a microcontroller vendor. Unrelated devices share it

docs/PROTOCOL.md is the reference for all of the above.

Verification

Most of this project cannot be covered by unit tests — it talks to a physical display, and the interesting behaviour is what the hardware does. So:

  • Say what you actually verified. "Builds, but not tested on hardware" is a fine answer. An unstated assumption is not
  • Screenshots of settings dialogs must be real screen captures. Control.DrawToBitmap() re-renders internally and does not match what is on screen. Use Graphics.CopyFromScreen() or a normal screenshot
  • docs/PROTOCOL.md records measured facts only. Anything not confirmed on hardware goes in marked as unverified, or in §9 under what remains unknown

Documentation lives in pairs

English is the source of truth; Japanese follows.

Changed Also update
User-facing behaviour README.md and README.ja.md
Understanding of the protocol docs/PROTOCOL.md and docs/PROTOCOL.ja.md
A dependency THIRD-PARTY-NOTICES.md (MPL-2.0 and similar carry notice obligations)
The version src/OpenDS360/OpenDS360.csproj and installer/OpenDS360.iss

Scope

OpenDS360 replaces the bundled software, so it holds itself to the things that prompted the replacement:

  • No network connections. Not for updates, not for telemetry, not for anything
  • Nothing displayed that the device did not report. No placeholder version numbers, no invented values
  • Failures surface. A corrupt settings file falls back to defaults, but a failed save is reported to the user rather than swallowed
  • No solution that weakens the user's security posture. PawnIO was chosen over WinRing0 precisely because it works with HVCI enabled

A change that trades one of these away for convenience will be declined, even if it works.

Licence

Contributions are accepted under the MIT Licence.