ssmithxandClaude Sonnet 5
c8f6102cfd
Build and validate / build (push) Successful in 11s
Gitea 1.27.1 on this instance silently ignores the ?template= param for .github/ISSUE_TEMPLATE/hardware-report.yml — the structured fields never render, just a blank title/body editor (confirmed live: same URL that's supposed to load the form shows nothing). Rather than debug Gitea's YAML issue-forms support, site/report.html is a plain form matching the schema that builds a title + markdown body (with a ready-to-merge YAML block) and opens Gitea's issues/new with them pre-filled via query params, which does work on this instance (verified live). Verified the full round trip in a real browser: filled the form, submitted, confirmed the opened Gitea tab has the correct title and a body containing valid YAML matching every field. Did not actually click "Create Issue" — no reason to leave a test issue on the tracker. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
57 lines
2.6 KiB
Markdown
57 lines
2.6 KiB
Markdown
# Contributing to ArchyHCL
|
|
|
|
Two ways to add a report, pick whichever's easier for you.
|
|
|
|
## 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, `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.
|