2026-09-01 11:32:58 +00:00
|
|
|
# Contributing to ArchyHCL
|
|
|
|
|
|
2026-09-04 02:49:02 +00:00
|
|
|
Two ways to add a report, pick whichever's easier for you. Either way,
|
|
|
|
|
running [`gather-hardware-info.sh`](https://hcl.archipelago-foundation.org/gather-hardware-info.sh)
|
|
|
|
|
on the machine you tested first is the easiest way to get accurate
|
|
|
|
|
CPU/RAM/storage/WiFi-chip values — it's local-only (reads `/proc`/`/sys`,
|
|
|
|
|
no network calls), read it before you run it like any script.
|
2026-09-01 11:32:58 +00:00
|
|
|
|
2026-09-03 22:37:27 +00:00
|
|
|
## Option A — use the report form (no git needed)
|
2026-09-01 11:32:58 +00:00
|
|
|
|
2026-09-03 22:37:27 +00:00
|
|
|
[Fill in the report form](https://hcl.archipelago-foundation.org/report.html) —
|
|
|
|
|
it opens a pre-filled Gitea issue with a ready-to-merge YAML block for you
|
|
|
|
|
(you'll still need a free Gitea account to post it). A maintainer copies the
|
|
|
|
|
block into a new data file and it shows up on the site.
|
|
|
|
|
|
|
|
|
|
(The repo's `.github/ISSUE_TEMPLATE/hardware-report.yml` structured issue
|
|
|
|
|
form doesn't render on this Gitea instance — it silently falls back to a
|
|
|
|
|
blank issue instead of showing the fields — so the site form above is the
|
|
|
|
|
supported no-git path, not the raw "New Issue" button.)
|
2026-09-01 11:32:58 +00:00
|
|
|
|
|
|
|
|
## Option B — open a PR directly
|
|
|
|
|
|
|
|
|
|
1. Copy `data/reports/example-thinkpad-t430.yml` to a new file named
|
|
|
|
|
`<device-slug>-<short-id>.yml` (e.g. `thinkpad-t430-a1b2.yml` — the
|
|
|
|
|
suffix just needs to make the filename unique if the same model's been
|
|
|
|
|
reported before).
|
|
|
|
|
2. Fill in your report. Every field is described in
|
|
|
|
|
[`data/schema.json`](data/schema.json); `issues` is required if your
|
|
|
|
|
`status` is `partial` or `broken`.
|
|
|
|
|
3. Validate locally before opening the PR:
|
|
|
|
|
```bash
|
|
|
|
|
pip install pyyaml jsonschema # if you don't have them
|
|
|
|
|
python3 scripts/build.py
|
|
|
|
|
```
|
|
|
|
|
This fails loudly (and tells you exactly which field) if anything's
|
|
|
|
|
wrong — same idea as [archy](https://source.archipelago-foundation.org/lfg2025/archy)'s
|
|
|
|
|
own `scripts/validate-app-manifest.sh`.
|
2026-09-04 02:49:02 +00:00
|
|
|
4. Open the PR. Once merged, deployment is automatic — a CI job rebuilds
|
|
|
|
|
`site/data.json` and pushes it live within seconds, no manual step
|
|
|
|
|
needed.
|
2026-09-01 11:32:58 +00:00
|
|
|
|
|
|
|
|
## Updating an existing report
|
|
|
|
|
|
|
|
|
|
Devices change over time (firmware updates fix WiFi issues, etc.) — if
|
|
|
|
|
you're re-testing a device that's already listed, open a PR editing the
|
|
|
|
|
existing file rather than adding a duplicate. Keep the old `tested_date`
|
|
|
|
|
context in mind: bump it to your test date so readers know how fresh the
|
|
|
|
|
report is.
|
|
|
|
|
|
|
|
|
|
## What makes a good report
|
|
|
|
|
|
2026-09-04 02:49:02 +00:00
|
|
|
- Be exact about the WiFi chip if you can (`gather-hardware-info.sh` above
|
|
|
|
|
gets this right on most Linux hardware; `iwconfig`/`lspci` by hand
|
|
|
|
|
otherwise, Device Manager on Windows if you dual-booted to check).
|
|
|
|
|
"Realtek" alone isn't as useful as "Realtek RTL8821CE" — chip-specific
|
|
|
|
|
driver issues are the single most common thing this list exists to
|
|
|
|
|
surface.
|
2026-09-01 11:32:58 +00:00
|
|
|
- If `status` is `partial` or `broken`, describe *what* broke and *how you
|
|
|
|
|
noticed* (crash on boot? WiFi drops under load? specific app won't
|
|
|
|
|
start?) — "doesn't work" isn't actionable for the next person.
|
|
|
|
|
- If you found a workaround, put it in `notes` even if the underlying issue
|
|
|
|
|
isn't fixed. A working-with-a-workaround report is more useful than no
|
|
|
|
|
report at all.
|
