Skip to content

Board source name leaks into extends: — manifests not portable across different source configurations #273

Closed

Description

@MEverett90

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

  1. 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.

  1. 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.

  1. 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

  1. jwinarske commented on Oct 20, 2026

    @jwinarske
    Contributor

    The trap is real, but narrower than stated: unqualified extends: already works.

    _boardExtendsBase tries 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), and emb boards list prints 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.yaml enforces nothing: two unrelated board repos can both declare name: boards, and the consumer then has no way out — whereas today --name is 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.yaml to supply the name when --name is omitted — note --name is required today, which is the actual gap this is feeling — keep --name authoritative 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/. Then extends: my-name/board is 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.toml names the dependency, registry config names where it comes from — and emb already has .emb/ and emb.lock to hang it on. More work than the --name default, but it fixes qualified names rather than discouraging them.

    One decision either way: a --name / .emb-source.yaml mismatch — warn or hard-error. I would warn.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions