# 2023.02 VMA

Date: 2023-02-27 (Monday)
Time: 10:00 CET
Moderator: José
Venue: https://meet.jit.si/RIOT-VMA-2023-02
Forum entry: https://forum.riot-os.org/t/virtual-maintainer-assembly-vma-2023-02/3859
Previous VMA forum entry: https://forum.riot-os.org/t/virtual-maintainer-assembly-christmas-2022-vma-2022-11/3812/5
Minutes:

Attendees (TBD)
---------------

- José
- chrysn
- Martine
- Koen
- Leandro
- Oleg
- Kevin
- benpicco
- maribu
- Kaspar
- Emmanuel
- Karl

Note taking: @chrysn (w. occasional help: Emmanuel)

Agenda
------
- VMA 2023.05 Moderation - 5min (José)
- Debrief 2023.01 Release - 5min (Kaspar)
- Outlook on upcoming 2023.04 Release - 5min (Kevin/José)
- 2023.07 Release Manager - 2 min (José)
- Summit 2023 Orga - 2 min (Oleg)
- Users vs. maintainers, who should we prioritize - 20 min (Kevin)
- [flash utils](https://github.com/RIOT-OS/RIOT/pull/18148) - 10 min (Kaspar)
- [SUBSYSTEMS.md](https://github.com/RIOT-OS/RIOT/blob/master/SUBSYSTEMS.md)
- modulenames and doxygen (Karl, about [PR19314](https://github.com/RIOT-OS/RIOT/pull/19314))

- AOB

## Notes

### VMA 2023.05 Moderation

Leandro will do this.

### Debrief 2023.01 Release

Kaspar: Went smooth as usual, thanks to those who helped with testing.
Kaspar: Tried to keep track of where issues come in (via actions, via issues, ...), tried GH project (didn't work well), tried pad (but needs manual syncing). Was OK because there was not too much to do this time -- so here is where things could be improved.

### Outlook on upcoming 2023.04 Release

- Kevin will manage this.
- Jose: Idea is to release end-of-April. Soft freeze -03-20. Hard freeze around -04-03.
- Kevin: Hope it won't be too challenging.

### 2023.07 Release Manager

Volunteers? Ben will do it.

Thanks from everyone.

(Also, that's whom Martine's script would have suggested).

### Summit 2023 Orga

- Oleg: About to set up the dates. Week of September 18th is the rough idea at the moment.
- Oleg: Please send ideas for keynote speakers.
- Oleg: This will include a 10y anniversary party, come up with ideas!

### Users vs. maintainers, who should we prioritize

- Kevin: What should we-as-a-RIOT-community prioritize? Should we priorize "users" to whom it's an operating system that's a separate entity that's configured and then built on top (with external boards / pkgs / libs) -- or priorize users-as-also-developers in the sense that going into internals is OK and expected?

- Kaspar: Shouldn't differentiate. Should consider ourselves as dumb users (because we are for most parts of the system). Differences would be about APIs etc, ... Making things as complicated as the maintainer thinks makes it hard for other maintainers. Simplicity and approachability of the code base is huge selling point. There can be specific things that are complex, but generally things should be approachable.

- Oleg: Can we actually expect any user to keep an overview over the entire system? I recently realized that back in my heavy usage days I liked RIOT for its simplicity and knew about everything in there, and nowadays that's limited to a small number of developers. Can't expect from RIOT users to know about all internals. It's getting more and more difficult to keep an overview. Thus, seconding Kaspar.

- maribu: Look at what's the state now. Most devs sit in comfortable Uni offices. We know little about users, and often don't give a shit. Even if AWS/Cloud connectivity is something company users do, we don't start working on it. The user group we want to have are hobbyists, and looking at what they do, they have Open Smart Home thingy ([Home Assistant](https://www.home-assistant.io/)), and that's what they use mainly, and we should consider this as a primary use case in addition to AWS because that's what users want. What we do is testing connectivity with Contiki, about which nobody cares any more. Another example: At FROSCON, people use AVRs and Xtensa. Colleague: "Y u surprised? could have told you." But even when we notice, we keep doing what we do already. We're currently favoring maintainers over users. Do we like this?

- Kevin: Agree, and that's why brought this up. "We care about maintainers more" is a possible outcome, but let's talk.

- Martine: Direction of Marian, maybe not as harsh. Picking up Oleg: Used to find it easy, now it's complicated. Maybe take off maintainer glasses sometimes and see how external user (or recent returnee) would look at it. HomeAssistant: Also that-other-system ... something with t?. (Not OpenHAB)

- Kaspar: Where does this pop up? What are the points where we need to make a compromise one direction or another?

- Kevin: See KConfig discussion. Hard to make it nice for user and maintainer. Hide complexity making it hard for maintainer, or pass it on to user?

- Karl: One hook line for RIOT is "like Linux for Desktop". For Linux you don't need to understand the kernel, you just put your app on it. If we want to get in this direction (which we already advertise), should have users in mind. Also: If we hide deails -- what kinds of users do we have? Even community free-time programmers around HomeAssistant might want to have some details and not hidden. In some subsystems I think we hide too much (which may drive off people who are into microcontrolers for control).

- Jose: Agree with basic feeling of "looks easy to us but using others it looks complex". We're not as easy as we claim to be. Interested in Oleg's experience: What is missing, what would have been done better? Hard to see from inside.
- Oleg: That'd lead to another discussion; would certainly volunteer to provide input here. Main problems are finding things in the documentation, b/c they're documented but it's scattered. Would need people like me or other newcomers to provide input/feedback. Sense consensus that we shouldn't forget about the users.

- Maribu: On trade-offs: flashutils, but it's not so much trade-offs or priorizatiojn. Raspi pico is next big thing for users/hobbyists, there's no progress. Other area is documentation. It's not a trade-off. If we had proper raspi pico support, there would be lots of benefits. It's about priorization.

- Ben: Wondering how often trade-offs occur. A good API should be good for both. Every user is also a developer. All agree documentation is important. It's a bit of an open-end discussion. Are we discussing Kconfig without discussing Kconfig? But I don't think that's related for maintainer-than-user, b/c even for user Kconfig is harder -- it's easier to create broken Kconfig than broken config with current system.

- Kevin: Bit of a separate discussion. Had lots of back-and-forth. Would be nice to settle on where do we want to draw the line, where can we priorize.

- Kaspar: Should just try as hard as possible to keep complexity out. If it's in, we and users have to maintain an extra layer to simplify for users. And learn how to say "no" to stuff.
- Martine: what do you mean with complexity here? Complex api? Complex backend implem?
- Kaspar: There is accidental complexity and inherent complexity. Peripheral should cater to the 90-95% use cases, and not the 5%, for which there can still be another API. That was an unwritten idea since beginning. Necessary complexity just needs to be contained and documented.
- Kevin: Jumping on peripheral. Users are not concerned with the internals there. By saying we only want to handle the 90%, seems we're more preferring the maintainers (b/c we deal with it) -- rather than hiding the complexity from users.
- maribu: Users of that 5% will have to deal with it in the application.

- Emmanuel: Who are our users? We only have a diffuse notion of what that is. If we can't know, we should decide who our users should be. Need to know the target to make documentation good. Let's open the discussion of who should our users be? E.g. if HomeAssistant or AWS users are our target, what APIs/examples/doc do we need? .... We need to make it more explicit. We need this information to decide the rest.

- chrysn (preparing) ad 5% and users: going out of our way to hide complexity can be detremental (leads user to use/learn other apis, which is good?) This will give wrong impressions to users.
- Kaspar: Had to sample 3 thigns at the same time with high frequency, but ADC function couldn't do it b/c there was coupling and thus too slow, and I had to rip it apart and make it MCU specific. That was quickly done for the application at hand. Having this in a generic way is maybe impossible, and not portable or not supportable on all MCUs. There's a gap between what we could implement with unlimited resources, and what we can actually do.

- benpicco: periph doesn't have grand design behind it. Often old and done for particular use case and particular devices. More inertia than grand design.
- maribu: Impacts how many developers we have. ...
- Oleg: Who's going to implement this? AWS or HomeAssistant or hardware platforms ... even if we know there are users who want this, we need people doing this. Most core RIOT devs mostly develop stuff they're interested in. It's hard to make RIOT devs work on features desired by outside users. How can we find the manpower to implement these?
- maribu: We have time for contiki compat tests ...
- Oleg: Because someone was interested in that. Back then, it was the only other system.
- Kevin: We have an outdated system but it takes 5min to test.

- Karl: On exposing complexity, we can do onion layers. Complex interfaces on bottom, usability on top. Like periph-timer as base frequency adjustment as base for ztimer linked lists as base for "sleep(ms)". For ADC case, we'll have people reading 3 sensors simultaneously. But others just want single poti read out ever now and then.
- maribu: That also reduces complexity. If there is a lower-level API things can be ported more easily, with mismatch fixed once in a layer on top.
- José: It's still fine to have hardware specific stuff in the driver callable, and do the generic stuff through abstractions.
- Karl: Sometimes our drivers are too far from the hardware.

- Kevin: Intermediate conclusion: We all agree on layered APIs.
- Kevin: Coming back to "Who are our users? Whom do we want to optimze for?" Can we come up with something now, or plan forward?
- Karl: Survey, maybe in forum?
- Kevin: Sometimes hear "There are many users but they don't say stuff". But reaching out just reaches the same people all over again. Maybe Twitter, IDK.
- Karl: External survey and link it from channels?
- Oleg: Not just looking for requirements of current, but more looking for potential users. (?: Both). Both. Wouldn't be surprised if there are hidden RIOT users, but finding potential user reqs wouldn't even work with Twitter. Maybe look at Eclipse Foundation's survey (e.g. https://outreach.eclipse.foundation/iot-edge-commercial-adoption-2022)
- benpicco: For potential users, why RIOT over Zephyr?
- Oleg: That's a question we need to answer first.
- maribu: Look at its RIOT's strong points.

- José: Sync on this in forum entry?
- Kevin: Start collecting information, start forum post, answer "what do we have over Zephyr" (which is the most marketed competitor).

### flash utils

- Kaspar: Looking at the diff ... yeah I think we can go with this. But try to restrict it to the 3 modules where it's used. We can maintain that, but let's not have it spread.
- maribu: In other modules, returns diminish. printf are already automatically converted. What we could do is convert puts to printf. But 95% of benefit is already there.
- maribu: Main use case is for users who'll do it in application.
- maribu: Can it be done on M3 where there's just a limited data flash portion? For Xtensa that works. But we're getting into details.

### Subsystems

- Ben: We now have a subsystem list. Please add yourselves: see [SUBSYSTEMS.md](https://github.com/RIOT-OS/RIOT/blob/master/SUBSYSTEMS.md)

### Module names and Doxygen
See [issue 7094](https://github.com/RIOT-OS/RIOT/issues/7094) related to [PR19314- sys: add modulenames for Doxygen](https://github.com/RIOT-OS/RIOT/pull/19314)

- Karl: Module name in front of Doxygen name would help discoverability. Currently, the mdoule name is often not discoverable (eg. 5x5 Font 'Mineplex')
- Karl: The PR just puts the module name just in front of the sys module name.
- Martine: Unless this is automated somehow, I don't think it'll ever be. I'd rather go with Makefiles. Otherwise it's the same whack-a-mole as with Kconfig.
- Martine: And we may still just want to go to sphinx-like documentation.
- Karl: Sphinx would also take doxygen titles.
- ben: It's pretty ugly to have them in the title. Sometimes there are multiple module names for different cases in the same driver (pseudomodules). Have them in the text.
- Karl: Some of our module names are quite ugly. "c++unittests" doesn't do tests, it's the test framework. Many titles don't even expose what it is for.
- Martine: Then you have to give the modules names that are descriptive of their functionality, and if two modules do the same (lwIP and GNRC) both called "networkstack"?
- José: We don't write user documentation, Doxygen just spits out what we put there with more or less random names. Some modules have something...
- Martine: Doxygen is API reference, not user documentation.
- José: Problem is to have a documentation of what you can use when. Module name needs to go somewhere too, but main problem is we don't have structured documentation for users.
- Kaspar: Can't we have module name as doxygen name? maribu: Modules can't be repeated. Martine: That's because we call things `cpu_periph` where it should be unique names instead.
- José: Issue is more to understand what a module does. Module name would have if we had such documentation, but we don't.
- Karl: Currently you may read about a library and you don't know which module to include. '5x5 Font Mineplex' is not a very important module.

- maribu: In man pages you have "what's the header file to include" and "what flag to set"
- Karl: man pages are named by the functions
- chrysn: They're not, they just have good aliases (vsnprintf -> printf).
- Karl: Just make it better than now, it doesn't have to be perfect yet.
- Kaspar: Agree. The module list is not useful.

- José: You go to modules and look for CoAP. Even with module names we'd still have that issue.
- Karl: So keep it as bad as it's now?
- José: We need better user documentation, that's an old [issue](https://github.com/RIOT-OS/RIOT/issues/8479).

- maribu: Could we just add a `Usage` section mandatory as first item in a doxygen group that only contains the list of header files to include and modules to select to be able to use it?
- Leandor: : we should use doxygen as it is as an API reference. It documents the API to a module -- so probably the name of the module should be name in the documentation. We also need docs on "when I want to do this, which module do I need to use"? And we don't have a mapping btwn module and API.
- chrysn: Module, functions *and* header files.

- Koen: On user side, I recently proposed [mdbook format](https://rust-lang.github.io/mdBook/format/markdown.html) docs. Could solve some of the questions "how do I create an application for CoAP" -- and leave Doxygen at API docs.
- Karl: Right now Doxygen doesn't have good discoverability for API docs.
- benpicco: What about multiple names?
- Karl: Like with man pages. One main name, and a list of other names. Submodules are currently often not even named.
- chrysn: there is open discussion as to if it should go in the title or not. At least we should have some data on usage in the description somewhere, and then if decided so move it to the title (script it?).
- José: Make sure data is here, and make it usable in automation. Then continue discussion.
- Kevin: User docs need a lot of effort.

- Emmanuel: We're a bit in the dark here. Sometimes we get positive feedback on our docs, other times we're wallowing in self-criticism. What should be our guidance? Who are our users? Need to characterize them. Else we cannot self-assess efficiently.

- benpicco: For some things docs are good, for some it's just bare minimum to pass CI.

- Koen: There's threshold with docs. If you have some experience with RIOT and documentation, then it's easy to map to code. If you're new, it's hard to figure out which parts of the docs you need, and then API docs are hard.

- José: Should we revive the old [issue](https://github.com/RIOT-OS/RIOT/issues/8479) on the forum?

### AOB

- Have a great week!
- Friday meeting, as always in VMA weeks, will be skipped!