Skip to content

Commit 46fc74c

Browse files
author
kitepon-rgb
committed
docs: 公開面を英語正本へ再構成し、ブランド適合の視覚素材とOSS導線を整える
README・プロトコル仕様・サードパーティ告知を「英語正本 + 日本語対」の構成にした。 kitepon.dev のブランド正典（色・identity・文体・チャネル方針）へ合わせ、 実機を撮影した動画から OG バナーと起動演出 GIF を作成している。 視覚素材: - .github/og.png (1200x630) を実機写真から作成。Night 背景、左上に kitepon.dev ロゴ、Discovery Orange をアクセントに使用。他製品の OG と同じ型 - .github/media/startup.gif に起動演出の実機動作を収録 - .github/media/pump-head.png に対応機種セクション用の実機写真 言語構成: - README.md を英語正本にし、既存の日本語版を README.ja.md へ移設 - docs/PROTOCOL.md を英語正本にし、日本語版を docs/PROTOCOL.ja.md へ移設 - THIRD-PARTY-NOTICES も同様に英語正本 + 日本語対へ 公開面の整備: - LICENSE の末尾追記を削除。GitHub が MIT と認識しない原因だった。 著作権表記を Quo (kitepon.dev) へ統一 - .github/workflows/ci.yml で Windows ビルドと自己完結発行を検証 - Issue テンプレート（動作報告・バグ）、SECURITY.md、CONTRIBUTING.md、 PR テンプレートを追加 - インストーラに日本語文書を同梱し、AppPublisher をブランド表記へ AGENTS.md に「公開文書は対で更新する」規約を追記した。
1 parent df65fdb commit 46fc74c

19 files changed

Lines changed: 1223 additions & 266 deletions

‎.github/ISSUE_TEMPLATE/bug.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: Bug report
2+
description: Something behaves differently from what the README describes
3+
title: "[bug] "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Before filing, two causes cover most reports:
10+
11+
- **The display goes dark on its own** — usually another program is writing
12+
to the device at the same time. `DeviceMonitorPcc` in particular must not
13+
run alongside OpenDS360.
14+
- **CPU temperature shows `0`** — [PawnIO](https://pawnio.eu/) is not installed.
15+
GPU temperature works without it.
16+
17+
- type: textarea
18+
id: what-happened
19+
attributes:
20+
label: What happened
21+
description: What you saw, and what you expected instead
22+
validations:
23+
required: true
24+
25+
- type: textarea
26+
id: steps
27+
attributes:
28+
label: Steps to reproduce
29+
placeholder: |
30+
1. …
31+
2. …
32+
3. …
33+
validations:
34+
required: true
35+
36+
- type: input
37+
id: version
38+
attributes:
39+
label: OpenDS360 version
40+
placeholder: v0.1.0
41+
validations:
42+
required: true
43+
44+
- type: input
45+
id: windows
46+
attributes:
47+
label: Windows version
48+
description: Run `winver`
49+
placeholder: Windows 11 Pro 24H2 (26200)
50+
validations:
51+
required: true
52+
53+
- type: input
54+
id: hardware
55+
attributes:
56+
label: CPU / GPU
57+
placeholder: Ryzen 9 9950X3D / RTX 5080
58+
validations:
59+
required: true
60+
61+
- type: dropdown
62+
id: pawnio
63+
attributes:
64+
label: Is PawnIO installed?
65+
options:
66+
- "Yes"
67+
- "No"
68+
- "Not sure"
69+
validations:
70+
required: true
71+
72+
- type: checkboxes
73+
id: exclusive
74+
attributes:
75+
label: Confirmations
76+
options:
77+
- label: DeviceMonitorPcc (the bundled software) was not running
78+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: The protocol documentation
4+
url: https://github.com/kitepon-rgb/OpenDS360/blob/main/docs/PROTOCOL.md
5+
about: Report layout, byte semantics, measured limits, and what stayed unknown.
6+
- name: Security issue
7+
url: https://github.com/kitepon-rgb/OpenDS360/security/policy
8+
about: Please report privately rather than in a public issue.

‎.github/ISSUE_TEMPLATE/hardware-report.yml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
name: Hardware report
2+
description: Tell us whether OpenDS360 worked on your cooler — success or failure, both are useful
3+
title: "[hardware] "
4+
labels: ["hardware-report"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
The compatibility table in the README grows from these reports.
10+
A report that it **did not** work is just as valuable as one that it did.
11+
12+
- type: input
13+
id: model
14+
attributes:
15+
label: Cooler model
16+
description: The name printed on the box or the retail listing
17+
placeholder: PCCooler CPS DS360 WH
18+
validations:
19+
required: true
20+
21+
- type: dropdown
22+
id: display
23+
attributes:
24+
label: What does the pump head show?
25+
options:
26+
- Digits only (seven-segment)
27+
- A colour screen with images or animations
28+
- Something else
29+
validations:
30+
required: true
31+
32+
- type: dropdown
33+
id: result
34+
attributes:
35+
label: Result
36+
options:
37+
- Worked — the temperature is displayed
38+
- Detected, but the display does not update
39+
- Not detected at all
40+
- Something else
41+
validations:
42+
required: true
43+
44+
- type: input
45+
id: vidpid
46+
attributes:
47+
label: VID / PID
48+
description: >
49+
Device Manager → the device → Details → Hardware Ids.
50+
Or run in PowerShell:
51+
Get-PnpDevice -Class HIDClass | Where-Object InstanceId -like '*VID*' | Select-Object FriendlyName, InstanceId
52+
placeholder: VID_2E3C&PID_0A15
53+
validations:
54+
required: true
55+
56+
- type: input
57+
id: product-string
58+
attributes:
59+
label: Product string
60+
description: Details → "Bus reported device description", if available
61+
placeholder: LIQUID COOLER DIGITAL DISPLAY - PCC
62+
63+
- type: input
64+
id: version
65+
attributes:
66+
label: OpenDS360 version
67+
placeholder: v0.1.0
68+
validations:
69+
required: true
70+
71+
- type: textarea
72+
id: notes
73+
attributes:
74+
label: Anything else
75+
description: >
76+
What you saw on the display, a photo, or where the behaviour differed
77+
from the README. Drag images straight into this box.

‎.github/SECURITY.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Security policy
2+
3+
## Supported versions
4+
5+
The latest release is the supported one. Fixes go into a new release rather than
6+
into patches for older tags.
7+
8+
| Version | Supported |
9+
|---|---|
10+
| Latest release | ✅ |
11+
| Anything older | ❌ |
12+
13+
## Reporting a vulnerability
14+
15+
Use **[Report a vulnerability](https://github.com/kitepon-rgb/OpenDS360/security/advisories/new)**
16+
under this repository's Security tab. That keeps the report private until a fix exists.
17+
18+
Please do not open a public issue for a security problem.
19+
20+
There is no guaranteed response time. This is a single-maintainer project, and
21+
stating that up front is more useful than a promise that might not hold.
22+
23+
## What is in scope
24+
25+
OpenDS360 runs with administrator rights and writes to a USB HID device, which
26+
makes the following the areas worth attention:
27+
28+
- **Writes that could damage the device.** Report IDs `0xF0` and `0xF1` are the
29+
presumed firmware update channel and are never written to. Any path that could
30+
reach them is a serious finding
31+
- **Privilege handling.** The app requires administrator rights; anything that lets
32+
an unprivileged process influence what gets written is in scope
33+
- **The Task Scheduler registration.** Registered under the current user with
34+
highest privileges. Any way to hijack the registered path is in scope
35+
- **Settings file handling.** `%APPDATA%\OpenDS360\settings.json` is parsed at
36+
startup; a crafted file causing anything beyond a fallback to defaults is in scope
37+
38+
## What is out of scope
39+
40+
- **Requiring a kernel driver for CPU temperature.** MSRs cannot be read without
41+
one. OpenDS360 relies on [PawnIO](https://pawnio.eu/), which is signed and works
42+
with HVCI enabled. Vulnerabilities in PawnIO itself belong to
43+
[its own project](https://github.com/namazso/PawnIO.Setup)
44+
- **Releases being unsigned.** Sources are public and every release asset carries a
45+
SHA-256 digest, which is what verification rests on today
46+
- **The bundled `DeviceMonitorPcc` software.** Findings about it belong to PCCooler
47+
and APALTEK. What was observed in it is recorded in
48+
[docs/PROTOCOL.md](../docs/PROTOCOL.md) §7 as the background to this project
49+
50+
## A note on network traffic
51+
52+
OpenDS360 opens no sockets and contacts no server. If you observe it making a
53+
network connection, that is a finding in itself — please report it.

‎.github/media/pump-head.png‎

363 KB
Loading

‎.github/media/startup.gif‎

2.8 MB
Loading

‎.github/og.png‎

474 KB
Loading

‎.github/pull_request_template.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
## What this changes
2+
3+
<!-- One or two sentences. What is different after this is merged? -->
4+
5+
## How it was verified
6+
7+
<!--
8+
This project talks to physical hardware, and most of it cannot be covered by unit
9+
tests. Say which of these applies — "not verified on hardware" is an acceptable
10+
answer, and far better than an unstated assumption.
11+
-->
12+
13+
- [ ] Verified on a real cooler
14+
- [ ] Builds, but not verified on hardware
15+
- [ ] Documentation or tooling only
16+
17+
**Model tested on:**
18+
19+
## Protocol safety
20+
21+
<!-- Only if this touches Hid/ or Display/. Delete otherwise. -->
22+
23+
- [ ] Nothing is sent to report IDs `0xF0` / `0xF1`
24+
- [ ] Display values stay clamped to 0–199
25+
- [ ] The 0.5 s send loop is never interrupted
26+
27+
## Documentation
28+
29+
- [ ] `docs/PROTOCOL.md` and `docs/PROTOCOL.ja.md` updated, if the understanding of
30+
the protocol changed (measured facts only; anything else marked unverified)
31+
- [ ] `README.md` **and** `README.ja.md` updated together, if user-facing behaviour changed
32+
- [ ] `THIRD-PARTY-NOTICES.md` updated, if a dependency was added
33+
- [ ] Version bumped in **both** `src/OpenDS360/OpenDS360.csproj` and `installer/OpenDS360.iss`

‎.github/workflows/ci.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths-ignore: ['**.md', '.github/media/**', '.github/og.png']
7+
pull_request:
8+
paths-ignore: ['**.md', '.github/media/**', '.github/og.png']
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: read
13+
14+
jobs:
15+
build:
16+
# The app targets net8.0-windows with WinForms, so it only builds on Windows.
17+
runs-on: windows-latest
18+
19+
steps:
20+
- uses: actions/checkout@v4
21+
22+
- uses: actions/setup-dotnet@v4
23+
with:
24+
dotnet-version: '8.0.x'
25+
26+
- name: Restore
27+
run: dotnet restore src/OpenDS360
28+
29+
- name: Build
30+
run: dotnet build src/OpenDS360 -c Release --no-restore
31+
32+
- name: Publish self-contained single file
33+
run: dotnet publish src/OpenDS360 -c Release -o dist/app --no-restore
34+
35+
- name: Verify the executable was produced
36+
shell: pwsh
37+
run: |
38+
$exe = 'dist/app/OpenDS360.exe'
39+
if (-not (Test-Path $exe)) { throw "$exe was not produced" }
40+
$mb = [math]::Round((Get-Item $exe).Length / 1MB, 1)
41+
Write-Host "OpenDS360.exe: $mb MB"
42+
# Self-contained builds bundle the runtime; a tiny file means the
43+
# runtime was left out and the build would fail on a clean machine.
44+
if ($mb -lt 20) { throw "Unexpectedly small for a self-contained build ($mb MB)" }

‎AGENTS.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,10 @@ PCCooler CPS DS360 のポンプヘッド上ディスプレイを制御する非
55
製品の説明と対応機種は `README.md`、通信仕様は `docs/PROTOCOL.md` にある。
66
**この文書はそれらを繰り返さない。ここに書くのは「知らないと事故る判断」だけ。**
77

8+
**公開文書は英語が正本、日本語が対。** `README.md` / `README.ja.md`、
9+
`docs/PROTOCOL.md` / `docs/PROTOCOL.ja.md`、`THIRD-PARTY-NOTICES.md` / `.ja.md` は
10+
必ず対で更新する。片方だけ直した状態で閉じない。
11+
812
---
913

1014
## 1. 最優先で守ること
@@ -97,10 +101,12 @@ CPU 温度は MSR からしか読めず、**PawnIO（カーネルドライバ）
97101

98102
| 変更したもの | 一緒に直す |
99103
|---|---|
100-
| プロトコルの理解が変わった | `docs/PROTOCOL.md`（**実測した事実だけ書く。推測は「未検証」と明記**） |
101-
| 対応機種が増えた／外れた | `README.md` の対応表 |
102-
| 依存ライブラリを追加した | `THIRD-PARTY-NOTICES.md`（MPL-2.0 等は告知義務あり） |
104+
| プロトコルの理解が変わった | `docs/PROTOCOL.md` と `docs/PROTOCOL.ja.md`（**実測した事実だけ書く。推測は「未検証」と明記**） |
105+
| 対応機種が増えた／外れた | `README.md` と `README.ja.md` の対応表 |
106+
| 依存ライブラリを追加した | `THIRD-PARTY-NOTICES.md` と `.ja.md`（MPL-2.0 等は告知義務あり） |
103107
| バージョンを上げた | `src/OpenDS360/OpenDS360.csproj` と `installer/OpenDS360.iss` の**両方** |
108+
| 配布物に文書を足した | `installer/OpenDS360.iss` の `[Files]` |
109+
| ブランド表記を変えた | `LICENSE` の著作権行と `installer/OpenDS360.iss` の `AppPublisher` |
104110

105111
---
106112

0 commit comments

Comments
 (0)