(Triggered by 17259, but sure affects other boards too).
Do we have a policy on the documentation requirements for (new; old to be weeded out on the long run) boards? If not, here’s a strawman policy I’d suggest:
Descriptions of boards need to contain:
Manufacturer by name and link
Alternatively, for boards distributed in electronic form to be etched and assembled by users, provider of the source.
Product name (and, if available, number) assigned by the manufacturer
If the manufacturer is known to sneakily update products and still keep the same PR name, a stable product identifier is required.
Information about where the board can be obtained from
Short description of the board (shape, connectors, case, noteworthy peripherals like radios or displays)
Link to English vendor documentation that contains the necessary information to review the board source code.
If no English vendor documentation is available, third party translations need to be linked, which are complete enough for a review.
If no vendor documentation is available (e.g. because it is a reverse engineered board), reverse engineering documentation can fill in for vendor documentation; this needs to be clearly documented, along with noteworthy shortcomings of the reverse engineering efforts.
Link to schematics, if available
Information about ways of programming (whether there is a bootloader, if yes which and how it is used, whether there is an on-board programmer or a programming header)
The contentious points are probably “English documentation” and “where to get it from”.
As for documentation, we can’t maintain something we can’t understand, and can’t understand something that is not either documented or well reverse engineered.
As for vendors, this runs the risk of becoming advertisement for particular vendors, but I’d rather have a few RS / Farnell / Mouser / Reichelt deep-links in there and know to be careful when I don’t see them, rather than look into a board only to notice later that it’s only available on Amazon or Aliexpress.
For English documentation, I don’t think it is that contentious. That seems to be the standard. Even on German vendor sites, I only can download the English data sheets most of the time (and if there are German ones, there are also English ones provided). Even if some might not agree, English currently is the de facto lingua franca in the world, in science, and in technology (as well as the RIOT community). If other languages are available, contributors are of course welcome to link that as well, but English documentation is a must, so that the community can benefit from it.
Regarding “where to get it from”, I don’t think that is necessarily needed. Common search engines will provide tons of vendors if you type in at least some information required by your proposal. On the flip side, a link can easily be used as advertisement or an affiliate link in disguise.
Regarding the documents in English. I really wouldn’t be too harsh on this. Especially for Chinese vendors. I agree this isn’t an ideal situation and it would be great if all vendors have an English documentation. Reality is thought that a lot of vendors don’t have it.
If you add this as hard requirement in order to get merged you end up in excluding a very large market.
I think it is more important to get a foot into the door and then push for more English documentation once you have a larger adoption.
After all the vendors have an interest in exporting their products.
Once a board gets merged into RIOT we have to maintain it, if documentation for a board is not in English then the hardware is unmaintainable. There is no way for me as a reviewer to even check that the mappings are correct. From that point of view only IMO English documentation is a must.
I do understand that having wide support for all possible hardware somewhere is very valuable, but I would not have that necessarily in the tree, it could be an external repository of boards with the teir idea. Those external boards could even have some simpler (not murdock, but github action based ci or something like that). But that is another thread altogether.
But what I would like to see is that boards in tree, or in tier 1 have better quality documentation in general, and having that in English is important, otherwise is not worth it for us to have it in the tree, or in whatever we would consider tier 1.
I would rather then say: Make it clear that these boards are not maintained by the core maintainer. Wasn’t there some discussion about a directory called contrib or something?
There was; and there was discussion of different tiers of boards, and that external boards work really well (they do, but such boards have bad discoverability).
I don’t know of any concrete proposals around that, especially as to whether that should be implemented as a documentation-only flag (pro: promoting and demoting is a single-line \ingroup change, con: needs that flag pulled out or synced with something Makefile-accessible for murdock), in a different directory (pro: better visibility in the source) or a different repo or even a list of different repos (pro: can have own maintainers, con: hard to integrate).
There’s the “staging/” proposal, which was a bit contested at the time. technically, it was reviewer blocked on disagreement over a single line.
With a bit updating (like, integrate EXTERNAL_BOARDS_DIRS), it would also work for boards.
So people with a board that doesn’t fulfill our requirements (to be fully determined but could be non english documentation and also hardware not available on the market) could still have their board support in their own repo and specify EXTERNAL_BOARDS_DIRS, without having to touch RIOT.
Doing things completely out of RIOT is certainly possible, but creates the risk of
duplicate work,
users turned away for lack of board support (even though it exists and is probably not even half bad),
RIOT developers not seeing easily how their APIs are used by boards (to judge whether something is an actually breaking change or not), and
(IMO most dangerous) creating disconnected downstream communities. The latter could happen when regionally popular boards get grouped together in some repo, and then issues are filed there and resolved with workarounds that might better be fixed here.
So I’d like to have something connected to RIOT where such boards can go, as long as the relation to RIOT is understood and visible.
I think my desired properties of any outcome are (not necessarily all realized from the start):
Contrib boards should be discoverable in the documentation (with due flagging).
Contrib boards should be easy to check out in batch.
A RIOT PR should have the option to “CI: Check contrib boards”. The outcome may not even be binary, and may need to be compared to nightly builds of the contrib boards to see whether it’s new breakage, but it’d be helpful when (say) changing things around a driver’s peripheral configuration.
I was not saying that we should always push people to use EXTERNAL_BOARDS_DIRS but only when our board requirements are not fulfilled.
RIOT can certainly officially support mainstream boards but for custom boards or boards without public datasheets or boards without documentation in english, using EXTERNAL_BOARDS_DIRS is certainly the way to go. For these custom boards, it’s not the responsibility of RIOT maintainers to maintain them or their compatibility with the RIOT codebase.
I’d say for boards that are available to the general public it’s preferable to have them in upstream RIOT, the quality of the documentation should not be a hindrance there if someone is still willing to do the work.
For common maintenance work (adoption to API changes) a look into the board documentation is hardly required, and often enough common terms (MISO, MOSI, LED, …) are universal across languages.