Repository navigation
Description
Problem
When a user adds a board registry source, they choose the source name themselves:
emb boards add github org/emb-boards --name my-name --transport ssh
Any extends: that uses a qualified name then embeds that choice:
extends: my-name/some-board-v1.0
This creates a portability problem in both directions:
- A manifest written by one developer only resolves correctly if every other developer names their source identically.
- A project manifest is not safely shareable unless all consumers coordinate on the same source name out-of-band.
The source name is effectively part of the manifest API, but it lives in the user's local ~/.config/emb/boards.yaml rather than anywhere versioned alongside the manifests themselves.
Alternatives considered
- Derive the name from the repo slug
Use the repository name (e.g. org/emb-boards → emb-boards) as the canonical source name, set automatically at boards add time. Simple and predictable. Downside: forks of the same repo collide, and a repo rename silently breaks existing manifests.
- Declare the canonical name inside the board repo (recommended)
Add a small metadata file (e.g. .emb-source.yaml) at the root of the board repository:
name: my-boards
emb boards add reads this file after fetching and uses its name as the source name, ignoring (or warning on mismatch with) whatever the user passed via --name. The canonical name travels with the manifests, is under version control, and is set by the board repo author.
This is the same model used by established package ecosystems: npm uses the name field in package.json as the package's canonical identity regardless of where it was fetched from, and Rust crate names are defined in [package] name in Cargo.toml — the registry index and all downstream Cargo.toml dependencies reference that name, not the repository URL or any user-assigned alias. In both cases the author controls the name, it is versioned alongside the code, and consumers reference it without any local coordination.
- Drop source-qualified names entirely
Require globally unique target names across all sources and make ambiguity a hard error with a helpful message. Board authors are responsible for namespacing their own target keys (e.g. myboard-arene-v11.0.28 rather than arene-v11.0.28). No source name ever appears in a manifest. Simpler for consumers, but relies entirely on naming discipline and breaks if two independent board repos happen to use the same target name.
Recommendation
Option 2. The board repo author is the right person to define the canonical name — they control the manifests, they know what name they want consumers to use, and the name should be stable across machines and teams without coordination. A .emb-source.yaml makes the name an explicit, versioned contract rather than an implicit local convention, consistent with how npm and Cargo handle the same problem.
Activity
jwinarske commentedon Oct 20, 2026
The trap is real, but narrower than stated: unqualified
extends:already works._boardExtendsBasetries the qualified key first, then matches on the target segment across every configured source — a unique match resolves, an ambiguous one is a hard error listing the qualified alternatives. That is option 3, already shipped, with qualified names kept as the escape hatch for the collision case. Every board, example and doc uses the unqualified form (raspberry-pi-family.emb.yaml:55,README:1213,training/emb-training.md:343,boards/emb-public/raspberry-pi.emb.yaml:13), andemb boards listprints unqualified targets grouped under a source heading.So the exposure is one sentence of documentation. README:1286 said
extends:"resolves as<source>/<target>" without mentioning that unqualified is the normal, portable form — that is what tells an author to write the non-portable thing. Two lines up, "so names never collide" is wrong about target names; the ambiguity error exists because they do. Fixed in #276.The npm/Cargo analogy does not carry. Those names are unique because a central registry enforces it at publish time. A
.emb-source.yamlenforces nothing: two unrelated board repos can both declarename: boards, and the consumer then has no way out — whereas today--nameis exactly the tool that fixes it. It also breaks a legitimate case: adding upstream and a fork of the same board repo, which need different names and different directories on disk.So option 2 as a default, not an override. Read
.emb-source.yamlto supply the name when--nameis omitted — note--nameis required today, which is the actual gap this is feeling — keep--nameauthoritative when given, and warn on mismatch. Option 1 is a reasonable fallback when the file is absent; its fork collision is already solved by--name.The option not listed, and the only one that makes a qualified name portable: let the project declare its sources, versioned beside the manifests — a
sources:block in the project's.emb/. Thenextends: my-name/boardis self-describing: the alias and the repo it maps to both live in the repo that uses them, and a consumer runs one sync instead of coordinating out of band. That is what Cargo actually does —Cargo.tomlnames the dependency, registry config names where it comes from — and emb already has.emb/andemb.lockto hang it on. More work than the--namedefault, but it fixes qualified names rather than discouraging them.One decision either way: a
--name/.emb-source.yamlmismatch — warn or hard-error. I would warn.