2026-09-01 11:32:58 +00:00
|
|
|
# Contributing to ArchyHCL
|
|
|
|
|
|
|
|
|
|
Two ways to add a report, pick whichever's easier for you.
|
|
|
|
|
|
|
|
|
|
## Option A — open an issue (no git needed)
|
|
|
|
|
|
2026-09-03 22:29:10 +00:00
|
|
|
[Open a hardware report issue](https://source.archipelago-foundation.org/ssmithx/ArchyHCL/issues/new?template=hardware-report.yml)
|
2026-09-01 11:32:58 +00:00
|
|
|
and fill in the form. A maintainer will turn it into a data file and it'll
|
|
|
|
|
show up on the site.
|
|
|
|
|
|
|
|
|
|
## 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`.
|
|
|
|
|
4. Open the PR. Once merged, `scripts/build.py` regenerates `site/data.json`
|
|
|
|
|
and the site picks it up.
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
|
|
|
|
- Be exact about the WiFi chip if you can (`iwconfig`/`lspci` on Linux,
|
|
|
|
|
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.
|
|
|
|
|
- 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.
|
