Hello RIOT developers,
changes like ,  and  prompted me to think about what promises a board's maintainers are making about stability. (That, as a side topic, touches on naming boards, but that's probably another can of worms).
Applications that only use the high-level APIs will not care about any of these: They work in terms of network interfaces and SAUL devices, and (in those examples) at worst they see that what used to be 3 ACT_SWITCH LEDs is now a dimmable RGB LED, and can work better with that (a SAUL consumer that didn't know the latter exists will see this as an opportunity to make sense of it).
Applications that use device abstractions are prone to some more changes: If in an application describes a DMX controller, it will at some point describe which UART_DEV the RS485 driver is connected to (possibly using UART_DEV(0) on BOARD=x, and UART_DEV(2) on BOARD=y, depending on where on their boards they actually plug it in). Those applications break when UART indices are shifted -- which may happen for example if there's a chip on the board that was previously dormant and is now enabled by a new driver and according board support.
And then there's even more customized applications that for some special task pick a very special on-board peripheral and configure it in their hardware specific way. These are most fragile, and break for example if a new more efficient timer implementation comes around that uses this previously unused-in-the-board piece of silicon. (Users of such approaches may get some security from, say, disabling a preconfigured timer and asserting that its underlying chip peripheral is really the .dev of that timer -- at least where there's some existing use of the silicon already).
I started off by suggesting some text to for inclusion with doc/doxygen/src/porting-boards.md, but really -- but taking a step back:
Do we have any existing text on these kinds of stability? Do we want to? If so, is that RDM material or really just a note to the board porting documentation?
Best regards Christian