Show 'made with / minimum version to open' next to the download

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

Overview Files Skills Discover Packages Releases Dependencies Issues8 Breadcrumbs Pull Requests Activity

Closed feature request

Ray · 2mo ago ·closed by Colby Knox

Problem

You can download a board's source and only discover it is unopenable after the download. Ray just hit this on adom/probing-workcell-load-cell-board: 46 MB down, then KiCad refused it —

KiCad was unable to open this file because it was created with a more recent version than the one you are running. To open it you will need to upgrade KiCad to version 10.0 or later (file format dated 20260206 or later).

The page said nothing about this. Nothing in the Files tab, nothing next to the download, nothing on the Overview. The requirement is knowable before the download — we just do not show it.

This gets worse as the wiki fills with boards authored on whatever KiCad the publisher happened to run. A consumer's first signal should not be an error dialog after a multi-megabyte download.

The data is already sitting in the files

No parsing effort, no dependency, no full-file read. Every field is in the first few hundred bytes. From the board above, verified:

file	fields in the header
`ProbingWorkcellLoadCellBoard.kicad_pcb`	`(version 20260206)` `(generator "pcbnew")` `(generator_version "10.0")`
`ProbingWorkcellLoadCellBoard.kicad_sch`	`(version 20260306)` `(generator "eeschema")` `(generator_version "10.0")`
`Brain.kicad_sch`	`(version 20260306)` `(generator "eeschema")` `(generator_version "10.0")`

Note (version …) is the file-format date and (generator_version …) is the application version — precisely the two numbers KiCad quotes back in its error. We do not have to infer a mapping or maintain a compatibility table: the file states both.

Note also the format dates differ per file type (pcb 20260206, sch 20260306), so a board's real requirement is the maximum across its files, not whichever file you happen to read first.

Ask

Put a compatibility line next to Download ZIP on the Files tab:

Made with KiCad 10.0 · needs KiCad 10.0+ to open

Refinements worth considering:

A per-file badge in the file tree, so Brain.kicad_sch carries its own requirement when someone downloads one file rather than the zip.
The same line on the Overview, since that is where most people land first.
Generalize beyond KiCad. Other formats on these pages carry equivalent headers: STEP declares its schema (FILE_SCHEMA(('AUTOMOTIVE_DESIGN { 1 0 10303 214 …, i.e. AP214) and GLB declares its container version (glTF magic + version 2) — both readable from the first bytes. Fusion and Altium files have their own. One "what do I need to open this?" surface can cover them all.

Please do not guess

If a file carries no version header, show nothing rather than an inferred or defaulted minimum. A wrong "needs 9.0" is worse than silence: it sends someone to install the wrong version and blame the file. Same rule the parametric data follows elsewhere — a value with no concrete source is not displayed.

Reported by Ray, from the KiCad 10.0 error on probing-workcell-load-cell-board. Related: adom/wiki#88 (the ZIP download this would sit beside).

2 Replies

Ray · 2mo ago

Implemented and up as a PR: https://github.com/adom-inc/git-wiki/pull/273

The Files tab now shows, above the tree:

Made with KiCad 10.0 · needs KiCad 10.0 or later to open · file format 20260306

Read straight from the file headers — (version …) for the format date and (generator_version …) for the app version, the two numbers KiCad quotes back — so there is no compatibility table to maintain.

Honouring the "please do not guess" ask literally: a file with no version header contributes nothing and the line disappears; a file with a format date but no generator_version (pre-KiCad-7) reports the date and makes no minimum claim. STEP (AP214) and glTF (glTF 2) are reported as formats, never as minimums, so a 3D-only repo shows no line.

One finding worth recording here: the newest file has to win. This board is format 20260206 in its .kicad_pcb but 20260306 in its schematics, so reading only the layout under-reports the project. There is a test pinning that.

Not done: the per-file badge in the tree, and the same line on the Overview. Both are straightforward follow-ups on top of the parser this adds.

Colby Knox · 2mo ago

Shipped and live on wiki.adom.inc. Your PR merged essentially as written, and the two design calls in it were the right ones: reading only the header rather than the file, and taking the newest format date across the project rather than whichever file is read first. The board that started this now says, before the download:

Made with KiCad 10.0 · needs KiCad 10.0 or later to open · KiCad file format 20260306

which is the same thing KiCad's dialog would have told you afterwards.

Two changes on top.

The header reads run off the event loop. readFileHead used spawnSync, so a Files-tab render with a cold cache fired a burst of synchronous git spawns, which is the freeze class the perf epic removed a few days ago. Memoizing per commit bounds how often that happens, not how long the loop stalls when it does. It is async now, with bounded concurrency of four: measured worst case at the file cap went from 124ms sequential to 58ms, and it no longer blocks anyone else's request. Overflow stays the normal path, since a real board file is megabytes and we ask for 4KB, so the reader relies on the partial read that comes back with the ENOBUFS rejection. There is a test pinning that on a 2MB blob, because it is the kind of behavior someone would later "fix" and silently break.

Authorship is read from the generator field instead of assumed. Colby spotted ws2812b-2020 reporting "Made with KiCad, file format 20240108". Neither of its files was made with KiCad:

(kicad_symbol_lib (version 20231120) (generator "adom"))
(footprint        (version 20240108) (generator "adom-footprint"))

They are KiCad-format files written by our own symbol and footprint pipeline. The parser keyed on the extension and ignored the generator field two lines below the version it was already reading, so a large share of the component corpus was claiming authorship the files contradict. It now reports "Generated by adom-footprint" with the format date and no minimum, because such a file states no application version at all. That is the same "please do not guess" rule you asked for, applied to authorship rather than only to version.

Worth recording: every fixture in both our test suites used pcbnew, so this passed CI on both sides. It took someone opening a real page to find it.

Not done, still open as you noted: the per-file badge in the tree, and the same line on the Overview.