# Contributing to ArchyHCL

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.

## Option A — use the report form (no git needed)

[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.)

## 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, deployment is automatic — a CI job rebuilds
   `site/data.json` and pushes it live within seconds, no manual step
   needed.

## 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 (`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.
- 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.