ArchyHCL/CONTRIBUTING.md

Contributing to ArchyHCL

Two ways to add a report, pick whichever's easier for you.

Option A — open an issue (no git needed)

Open a hardware report issue 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; issues is required if your status is partial or broken.
3. Validate locally before opening the PR:

   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'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.