From 1dd05f268032252e71f5155edf8de86bfdd85923 Mon Sep 17 00:00:00 2001 From: zackees Date: Tue, 30 Jun 2026 11:08:04 -0700 Subject: [PATCH] docs: record dump_usb_ids anti-removal policy (#720) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #720 escalates the policy after #719's near-removal of `crates/fbuild-core/examples/dump_usb_ids.rs` to a documented anti- removal rule. The example is tier-1 of the nightly USB-VID merge (`.github/workflows/update-data.yml` -> `tools/merge_sources.py`), and the `usb-ids` workspace dep exists only for it; removing the example would also remove the dep, dropping the aggregator from 4 → 3 independent sources of truth. Two doc additions: 1. Banner in `crates/fbuild-core/examples/dump_usb_ids.rs` explicitly tells future LLM-driven cleanup passes to read #720 before deleting, and explains the dependency-coupling rationale. 2. `crates/CLAUDE.md` `fbuild-core` row mentions the example + policy so it surfaces in the per-crate routing the existing doc structure uses. Closes #720 --- crates/CLAUDE.md | 2 +- crates/fbuild-core/examples/dump_usb_ids.rs | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/crates/CLAUDE.md b/crates/CLAUDE.md index 096de515..9afd8d3c 100644 --- a/crates/CLAUDE.md +++ b/crates/CLAUDE.md @@ -57,7 +57,7 @@ fbuild-test-support (test utilities) ────────────── ## Crate Responsibilities -- **fbuild-core** — `FbuildError`/`Result`, `BuildProfile`, `Platform`, `SizeInfo`, `DaemonState` +- **fbuild-core** — `FbuildError`/`Result`, `BuildProfile`, `Platform`, `SizeInfo`, `DaemonState`. Also ships the `dump_usb_ids` example (`examples/dump_usb_ids.rs`) — **tier-1 source** for the nightly `online-data` USB-VID merge (FastLED/fbuild#720). Do not delete; the `usb-ids` workspace dep exists *only* for that example, so removing it drops the aggregator from 4 → 3 independent sources. - **fbuild-config** — `PlatformIOConfig` (INI parser with `extends` inheritance), `BoardConfig`, `McuSpec` - **fbuild-paths** — Dev/prod path isolation (`~/.fbuild/{dev|prod}/`), port mapping (8765/8865), cache dirs - **fbuild-packages** — URL-based package downloads, toolchain resolution, library manager, parallel pipeline diff --git a/crates/fbuild-core/examples/dump_usb_ids.rs b/crates/fbuild-core/examples/dump_usb_ids.rs index 76c54596..b8736183 100644 --- a/crates/fbuild-core/examples/dump_usb_ids.rs +++ b/crates/fbuild-core/examples/dump_usb_ids.rs @@ -1,5 +1,26 @@ //! Dump the bundled `usb-ids` database as a JSON object to stdout. //! +//! # DO NOT REMOVE — anti-removal policy (FastLED/fbuild#720) +//! +//! This example is **tier-1** of the USB-VID name merge. It is invoked +//! by the `Update data` workflow (`.github/workflows/update-data.yml`) +//! to export the bundled [`usb-ids`](https://crates.io/crates/usb-ids) +//! crate snapshot as JSON; `tools/merge_sources.py` then unions that +//! with the linux-usb.org mirror, the usbids GitHub mirror, and the +//! curated `vendor_names_inlined.py` overlay to produce the published +//! `online-data/data/usb-vid.json`. +//! +//! The fbuild **runtime** USB resolver (`fbuild-core::usb::resolver`) +//! does not depend on this example — it uses the compile-time-embedded +//! `usb-vendors.tar.zst` (`fbuild-core::usb::embedded`). The `usb-ids` +//! workspace dependency is now pulled in *only* by this example, so +//! removing the example would also remove the dependency, dropping the +//! aggregator from 4 → 3 independent sources of truth. Decoupling +//! recorded in #719; anti-removal policy in #720. +//! +//! If your LLM-driven cleanup pass flagged this file as "dead code," +//! it is not — please read FastLED/fbuild#720 before deleting. +//! //! Used by the `online-data` branch's nightly workflow (see //! `.github/workflows/update-data.yml`) as one of the input sources //! for the merged `usb-vid.json`. Running this example via