ssmithxandClaude Sonnet 5
a22a9c9826
Build and validate / build (push) Successful in 1m38s
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>
51 lines
2.2 KiB
Markdown
51 lines
2.2 KiB
Markdown
# 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](https://source.archipelago-foundation.org/lfg2025/ArchyHCL/issues/new?template=hardware-report.yml)
|
|
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.
|