RDM: Naming boards

[chrysn]

Contribution description

I was recently very frustrated with how off-brand boards were documented.

This is supposed to fix this:

rendered

Issues/PRs references

There are probably issues around for concrete boards / board groups whose naming was problematic, but I haven't found them yet.

[chrysn]

As for a transition plan (which I think is best discussed outside of the text, which would persist after transition is over), I'd suggest that

• new boards are named following the conventions,
• particularly broken boards are renamed and fixed without aliases in place,
• some aliasing mechanism is added (which may just be a simple Makefile magic table, so that everything after some line in the Makefile just sees the canonical name). Some aliases may be deprecated, or we just leave them around.
• all boards are renamed (which is now non-disruptive because aliases are in place).

There might be parallel efforts in restructuring the documentation (eg. grouping the list by vendor, and/or ensuring that the doxygen names of the boards match the technical names), but that should be independent.

[aabadie]

https://github.com/RIOT-OS/RIOT/pull/7976 might be useful for board aliases. It's a bit dated but could already be a good start.

[chrysn]

Thanks, yes, #7976 would pretty much be the alias solution. (It even looks like it'd be extensible if we want to handle the "well-known prefixes" part just through aliases, although then we'll have to be wary of questionably-trademarked vendors like stm32-base...). I'd hope that agreeing on a structure for names would not depend on progress on the aliases, but I'm trying to revive that anyway.

[chrysn]

Thanks for you input and reviews. In fixups, I have

• placed an explanation of BBC being a well-known prefix of Micro:bit Educational Foundation, replacing a "this needs a better explanation" comment,
• accepted typo fixes,
• removed the motivation section (that was announced to be removed), and
• added an acknowledgements section.

I'd let this sit for a few days more (which is no requirement of the process, but something I consider good practice), and unless NACKed, will

• set the status to consensus,
• reflow the text to conform to the fixed-width format of RDMs,
• set the RDM number (probably 2) in the header and the file name, and
• merge this.

[miri64]

If there is still time, before this is merged, can you also please (maybe as a final step before merging) reformat the raw text, so it is also somewhat easier to read. While nice for version control, to have ever sentence (and half-sentence) in a line, it makes it a bit hard to read when the RDM is e.g. opened in a terminal.

[chrysn]

Yes, that's one of the final steps on my list. (And as there has now come in controversial feedback, I'd give us some more time to finish the bikeshedding of noname/generic(brand)/offband/acme).

[MrKevinWeiss]

So a few things:

• :heavy_check_mark: vendor+product+sn is usually a common we to identify unique devices, this could better allow for that by encoding the vendor into the name
• :grimacing: This means extra typing for users when running boards, small issue, but introduces more typos and makes readability of copy-paste commands a bit harder
  • Though this can be offset by alias somewhat
  • Also autocomplete for boards could help
• :raised_eyebrow: Should we also encode revision data in as well?
• :raised_eyebrow: What about also assigning simple numbers to the board as well (I am thinking how protobuf deals with backwards compatibility)?
  • If my everyday is working with say and esp32-wroom-32 and a samr21-xpro liek can be a lot easier if I get used to BOARD=3 make and BOARD=62 make rather than typing...
• :heavy_check_mark: Better categorization when looking at the sorted list

I feel like this is a step in the direction of providing boards with more metadata that would eventually allow things like skipping some boards for CI, though I image it would not all be encoded in the directory name.

[MrKevinWeiss]

Also should we say anything about matching some label of the board. Ideally we should be able to look at a board and know what the name is (which is not the case with the phytek boards).

[miri64]

• If my everyday is working with say and esp32-wroom-32 and a samr21-xpro liek can be a lot easier if I get used to BOARD=3 make and BOARD=62 make rather than typing...

How would this numbering work? What criteria makes a board Number One? IMHO, this is something we can leave to the user, if they would put an order to board, As such, I'd say, once aliasing is in place, this should be done via some local aliasing and thus, a potential point for the wishlist for aliasing is "allow for user defined board names" ;-).

[chrysn]

a potential point for the wishlist for aliasing is "allow for user defined board names" ;-).

Briefly continuing out-of-scope: This could also be "third party defined names". Like, if someone came up with The Awesome Numerology of Boards, BOARD=tanob:42 could become an alias to whichever name we use for that board.

[benpicco]

Should we also encode revision data in as well?

Maybe a bit off-topic, but we have

ifneq (, $(BOARD_VERSION))
  BOARD := $(BOARD)-v$(BOARD_VERSION)
  CFLAGS += -DBOARD_VERSION=$(BOARD_VERSION)
endif

I know BOARD_VERSION is currently used a bit different in upstream RIOT, but I'd say using it as an optional postfix could be useful in general.

[chrysn]

[oups, that was sitting unsent here while I've been replying via mail...]

typing

Aliases can help, and so will the known prefixes (which eventually might be handled by aliases). Yes it's more even to copy-paste, but especially when copying from documentation it also gives immediate information that helps match the value on screen with the box before you.

revision data

That's getting into "what is a board" (which is good but maybe going too far here). The way it is now (and unchanged through the RDM draft), a board is "everything that is built from setting that BOARD variable". If it so happens that the same code (possibly with runtime switches to detect whether a variant is the case) can serve many variants, the variant does not need to be encoded. Once a variant is relevant to the generated code (even in the linker script, see current blue/-blackpill boards), it becomes a different board.

Picking up benpicco's point -- that we can do, but we should be aware that this is something different than aliases. An alias would be resolved and then passed on in resolved form, it's two names for the same thing. If we allow this, we'd have different boards sharing a code base, so we can ifdef around things, rather than having two code bases where one just pulls in common components from the other. It may well make sense to do something like that, though.

matching a label on the board

That's nothing we can help with. With some boards, creators will be consistent between how they label the box / name the item they are selling and what they print on the board, with others, not. Once we have aliases, we can consider whether some labels on boards also make good aliases.

numbers

I'm not a big fan. On the user interface, it's inviting subtle errors (we're in the 3 digits already, and was it board 157 or 175?). On the management side, it'd need more coordination (can't handle numbers in conflicting PRs), and if we wanted to give protobuf style immutability guarantees, we'd need a way better understanding of what it means for a board to be compatible than we have now.

[chrysn]

This has the necessary approvals, and as far as I've kept track, all concerns were addressed with resolutions accepted (implicitly assumed when following a suggestion in the concern) or claimed to be out-of-scope (in particular, board versioning and inheritence).

I've squashed to get green CI, and am leaving this for another 24h late review period before pushing the merge button.