ssmithx/ArchyHCL

Fork 0

Files

T

ssmithxandClaude Sonnet 5 a22a9c9826

Build and validate / build (push) Successful in 1m38s

Details

Initial scaffold: ArchyHCL, a community hardware compatibility list for Archipelago

Modeled on three researched precedents (see README): OpenWrt's Table of
Hardware for the browsable sortable/filterable table UX, postmarketOS's
working/community/testing tiers for the status field (collapsed to
working/partial/broken here), and RaspiBlitz's scattered GitHub-issues
approach as a negative example to avoid — hence structured YAML report
files validated against a JSON Schema instead of free-text issue threads.

- data/reports/*.yml + data/schema.json: one file per report, schema
  requires `issues` whenever status is partial/broken
- scripts/build.py: validates every report and builds site/data.json,
  fails loudly on bad data (same idea as archy's own
  validate-app-manifest.sh)
- site/: plain HTML/CSS/JS, no framework or build step, fetches data.json
  client-side — search, filter by status/form-factor, sortable columns,
  click a row for issues/notes detail
- .github/ISSUE_TEMPLATE/hardware-report.yml: structured submission path
  for contributors who don't want to touch git directly
- .gitea/workflows/ci.yml: runs the build/validate step on push and PRs

Not yet deployed anywhere — see README's Deployment section.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-09-01 11:32:58 +00:00

2.2 KiB

Raw Blame History

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

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).
Fill in your report. Every field is described in data/schema.json; issues is required if your status is partial or broken.
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.
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.