Merge pull request #18589 from chrysn-pull-requests/rdm-board-names

RDM: Naming boards

doc/memos/rdm0003.md

@@ -0,0 +1,167 @@
+- RDM: 3
+- Title: Board names for RIOT boards
+- Author: Christian Amsüss
+- Status: Active
+- Type: Design
+- Created: 2022-09
+
+## Abstract
+
+This memo describes how boards are assigned names in RIOT.
+
+## Status
+
+This document is a draft and reflects the author's opinion.
+
+## Terminology
+
+This document does not attempt to define what "board" means within RIOT;
+for the purpose of this document,
+a "board" is the name for the group of devices built with the same `BOARD` variable.
+A board's "technical name" is the corresponding value of the `BOARD` variable;
+its "friendly name" is the text by which it is shown in documentation.
+
+A board's "defining representative" is a distinct piece of hardware
+which the maintainers of that board picked.
+This distinction is only relevant for boards containing devices created by multiple vendors;
+typically, the other boards are (unauthorized) clones
+or forks (of Open Hardware boards)
+of the defining representative.
+
+# 1. Introduction
+
+In order to facilitate discovery of boards,
+and to avoid confusion disappointment with advertised boards,
+this memo describes the structured naming of boards.
+
+It makes recommendations as to which information is to be included in documentation
+where it comes to naming,
+but does not influence how boards should generally be documented,
+or which boards are acceptable for inclusion.
+
+The memo describes a state of RIOT that is not immediately attained
+when it becomes a consensus document;
+the technical aspects of migrating to that state are discussed in the RDM pull request.
+Until mechanisms are available for compatibly renaming boards
+(such as those of section 4),
+boards should not be renamed merely to comply with this scheme,
+and new members may still be introduced to existing families with names matching preexisting conventions.
+
+# 2. Board naming
+
+The friendly and the technical name are for boards are derived
+from a designation assigned by the vendor of the defining representative.
+They are composed from the vendor's name and the name chosen by the vendor,
+unless the vendor uses a well known prefix for the board.
+
+When vendor names contain components that are common in names but uncommon in use,
+these are removed.
+For example, "Microchip Technology Inc." is rendered as "Microchip",
+Vendors that primarily use a particular shortened form of their name
+are addressed by that name ("MikroElektronika d.o.o." uses "MIKROE").
+
+As vendors commonly use multiple names for themselves or products
+(eg. "Thunderboard", "Thunderboard Sense" and "SLTB001A"),
+it is up to the board's maintainer to select pick a name
+that is likely to be usable for a long term.
+Marketing names are often unsuitable,
+as vendors (such as "Galaxy A7") might release later revisions without a clear name distinction.
+
+For the **friendly name**,
+the vendor's name and the product name are taken verbatim from the vendor,
+including stylization and capitalization, as far as that is possible within Unicode:
+Examples are "Arduino", "PHYTEC", "micro:bit" and "TRÅDFRI".
+
+A list of vendor names, along with their well known prefixes,
+is maintained as part of the RIOT documentation.
+
+For the **technical name**,
+the friendly names are reduced to the set of lowercase ASCII characters, digits and the dash (`-`) character.
+As a general rule, whitespace in the name is replaced with a dash.
+The precise conversion is left to the maintainer;
+they are encouraged to consider the source language's and ecosystem's conventions.
+For example, "TRÅDFRI" becomes "tradfri"
+and "micro:bit" becomes "microbit"
+(both because that's what the respective vendors use in their URIs).
+
+The vendor and product name are concatenated
+by a space (` `) to form the friendly name,
+and by a dash (`-`) to form the technical name.
+If the product name uses a prefix out of the well known prefix list,
+the vendor name and concatenating character are left out from both names.
+In the context of the vendor,
+the friendly name may be used without the vendor part,
+for example when listing all boards from one vendor.
+
+Note that names can not be reliably split into the vendor and product name;
+such a split can only be performed through inspecting metadata of the board,
+if such are defined.
+
+## Unstructured vendors
+
+Some boards do not have a clear vendor,
+but just "pop up" on online stores.
+Examples are the "bluepill" series,
+and the boards [documented as "nRF52 DK" at the time of writing](https://web.archive.org/web/20211015201641/https://doc.riot-os.org/group__boards__nrf52dk.html).
+
+Unless and until a well-structured vendor of a defining representative is found,
+these are filed under the "Generic" (technical name: "generic") vendor.
+The product name is assigned by the maintainer based on any common term for the boards.
+
+For such boards,
+it may be useful to document links to typical sources,
+preferably as Wayback Machine snapshots (given that sources may be volatile).
+
+# 3. Examples
+
+* The "Adafruit PyBadge" uses the technical name "adafruit-pybadge".
+
+  There are other devices currently covered by this board
+  (the PyBadge LC and the EdgeBadge),
+  but the PyBadge is the defining representative.
+
+* The "Silicon Labs EFM32GG-STK3700" uses the technical name `silabs-efm32gg-stk3700`.
+
+  The technical name for Silicon Labs is `silabs` as used in their web site.
+
+* The "STM32F7508-DK" uses the technical name "stm32f7508-dk".
+
+  STM is a well-known prefix of STMicroelectronics.
+
+* The "BBC micro:bit v2" uses the technical name "bbc-microbit-v2".
+
+  "BBC" is the well known prefix the Micro:bit Educational Foundation uses for their boards.
+  (The development stems from a project led by BBC Education, which explains the name's presence.)
+
+* The "Generic nRF52 DK" uses the technical name "generic-nrf52-dk".
+
+  It is thus clearly distinguished from the nRF52-DK product from Nordic Semiconductor,
+  which is named "nRF52 DK" ("nrf52-dk") based on the vendor's well-known prefix.
+
+# 4. Aliases
+
+Aliases for board names may be used as a transition mechanism,
+to address cloned / forked boards under their new vendor's name,
+to remove the need for the "well-known prefixes" rule,
+or when renames are necessary.
+
+A mechanism for such aliases is out of scope of this memo.
+
+## Acknowledgements
+
+Thanks to
+Kaspar Schleiser,
+Alexandre Abadie,
+Marian Buschsieweke,
+Koen Zandberg,
+Martine Lenders
+and Benjamin Valentin
+for their comments, suggestions and review.
+
+## Revision
+
+- Rev0: initial document
+
+## Contact
+
+The author of this memo can be contacted via email at <mailto:[email protected]>.