Repository navigation
Reporting errors
Most parts lists are read by machine from PDFs, scans and schematic images, so some come out wrong. Reports are the main way those get fixed. All reports go through GitHub issues on drlholloway/akashic, which offers one form per kind of report.
| Problem | Form | Label |
|---|---|---|
| A circuit's parts list, controls, original or enclosure does not match its build document | Wrong parts list | parser |
| A vendor, project host or schematic archive that should be indexed | Vendor request | vendor |
| Something on the site misbehaves, shows wrong data or does not load | Bug report | bug |
| A filter, view, data field or workflow that would help | Feature request | enhancement |
Security problems go through private reporting, not a public issue.
Every circuit page has a Report a wrong parse button by the parts list. It opens the Wrong parts list form with two fields already filled in:
- the title,
Wrong parse: <circuit name> - Circuit URL in the library, the page you were on
You fill in the rest:
- What the build document says: the rows or fields that are wrong or missing, as the vendor's document prints them (required).
- What the library shows: what the circuit page has instead.
Before reporting, look at the small mark beside a value in the parts list. It tells you how the value was read:
| Mark | Meaning |
|---|---|
| (none) | Read from a text table, an interactive BOM or a CAD file: exact unless the source or the parser is wrong |
ocr |
Read from an image by OCR |
sch |
Paired from labels on the schematic drawing, not from a parts list |
fixed |
Corrected by hand (outranks the other marks) |
Rows from layouts and schematic images read by eye carry a note saying so ("read from the layout by eye", "read from the schematic by eye"), and a circuit may show a Check before you build list of values the reader was not sure of. Marked and noted values are the likeliest to be wrong, but text-table rows can be wrong too when a parser misreads a table layout.
- The library URL of the circuit (the button fills this in).
- The exact rows from the build document: designator and value, for example
R7 is 4K7 in the doc, the library shows 47K. A page number in the PDF helps. - Missing rows as well as wrong ones: "C12 to C15 are not listed".
- For controls, enclosure or "based on", quote the document or the product page.
- If the vendor's own document has a typo, say so; the fix keeps the right value and marks
it
fixed.
You do not need to know which parser read the board.
Use the Vendor request form with:
- the shop or index URL (required);
- a link to one build document or schematic, so the document layout can be checked;
- anything useful: the platform (WooCommerce, Shopify, Big Cartel, Wix...), roughly how many boards, licensing notes, whether the store is still open.
Stores, project hosts, layout sites and schematic archives are all in scope, and so are
closed stores (see the data/archive/ note in How the data is made).
Use the Bug report form: the page URL, what you did, what you saw and what you expected, and the browser and device (including whether the site was installed as a PWA).
A report gets one of two fixes:
- A parser change, when the same mistake affects many boards. It goes through the workflow in Fixing a parse.
-
A hand correction, when the misread is a one-off: single rows in
scraper/pcblib/corrections.py, or a whole parts list read by eye inscraper/pcblib/transcribed/.
Hand corrections are applied in db.upsert_circuit every time a board is stored, after every
parser has run. A weekly refresh or a full rescrape therefore re-applies them: a fixed row
stays fixed. Each correction carries a comment saying where it came from and when it was
checked, and is removed when a parser learns to read the board right.
The live site picks the fix up at the next deploy; the weekly refresh deploys on Sundays when its audit is clean (see Releasing).