Organisation structure

[therealprof]

At the moment the stm32-rs organisation is just a loose bundle of various STM32 related repositories and crates without any overarching governance, teams or rules. This leads to varying quality and completeness as well as a different pace of development in the crates despite lots of overlap and a unified interest in thriving Rust ecosystem.

In order to better support the development of the various resources we should:

• Manage the teams organisation wide instead of per crate
• Define minimum quality standards for included repositories, such as
  • Need to have at least two active team members taking care of issues and PRs
  • Need to have a usable README, mentioning all supported features and pointers how to get started and how to contribute as well as a MSRV
  • Need to have an acceptable license
  • Need to use CI to ensure compilability of all supported features
  • Need to be published on crates.io unless there's there's a good reason not to (e.g. not a Rust crate or a collection of examples)
• Provide issue tracking and guidance for cross-repository issues
• Set up a organistation front explaining the mission, of the organisation, the rules and providing an overview over and link to the included repositories

[adamgreig]

Thanks for writing this up!

Manage the teams organisation wide instead of per crate

Do you expect we'd still have one team per HAL, and then perhaps a few other teams for the smaller repos?

[therealprof]

Do you expect we'd still have one team per HAL, and then perhaps a few other teams for the smaller repos?

Not quite sure where this will lead, but I could imagine that we start with a team per family which would take care of the HALs and the BSP/example repos for that particular family and then additional special interest teams for USB, eth and stm32-rs. It would be great if we ended up with more family-independent crates in end.

[hannobraun]

* Need to have at least two active team members taking care of issues and PRs

I don't have a strong opinion, just thinking out loud:

• Could this requirement hinder the growth of teams? Quickly including a well-written one-author HAL might give it the exposure and structure it needs to attract contributors.
• If that doesn't happen, are we (as a community) somehow better off if an unmaintained (or poorly maintained) HAL lives outside the organization? Having it outside might just lead to a bunch of one-off forks by people using the hardware. Having it in the organization might focus the efforts of contributors, neither of which would be willing to become a full maintainer by themselves.
• Or to rephrase the previous point somewhat: If the manpower to fully maintain a HAL is not there, might the stm32-rs org serve to at least focus the available manpower, leading to a somewhat better (if not optimal) result?

[therealprof]

The idea is to ensure that repositories are and keep on being actively maintained. It is certainly possible that the the org will (in the interim) provide resources to keep the ball rolling and help to find new maintainers in case contributors move on to other projects. The popularity and focus of the organisation will certainly help with that.

Unclear or unresolved maintenance is in my opinion the main reason for diverging forks. If there's no interest in collaboration from the original author of a repository why should we provide a platform for it? If a maintainer of a fork manages to form/attract a group of contributors and turn the fork into something bigger then it makes more sense to accept the fork into the organisation than the original.

I don't see much point in having deserted repositories around. People on matrix have complained about unresponsive maintainers recently which is something we'd like to address here.

[hannobraun]

Well, all I'm saying is, inactive maintainers and unmaintained repositories will still exist, whether it's inside or outside of the org. I think there's benefit in having them inside the org, because the exposure can attract contributors/maintainers and because it provides a focus point for casual contributors to work as common co-maintainers (which might not happen outside of the org; inside of it, an admin can just make people maintainers). That's the point of having them around, in my opinion.

I think it's a question of vision and goals: Is the org an unstructured place where those interested in STM32 chips can collaborate? That's kind of the current situation, and my argument is intended to highlight some of the advantages that has. Or is the org supposed to be a focused effort to develop a high-quality STM32 ecosystem? That seems to be what you have in mind, and I'm not against that.

[therealprof]

The idea is not to kick out repositories. Once they're in, they're in for good.

Instead this is trying to define criteria to make sure that collaboration can happen and maintenance is secured. Currently if a repository is abandoned or the sole maintainer is not responsive, there's very few (friendly) actions the org can take to rectify that situation which is not ideal.

This discussion is just a baby step to improve the organisation, manage expectations and allow the organisation to step in and help shaping and maintaining the ecosystem.

I don't expect the implementation of such a structure alone to have a big impact on anything, it's just a spelled out version of how we roll (or would like to). ;)

[hannobraun]

Makes sense 👍

[bbrown1867]

Hi there 👋 - new to this community and looking to get more involved. Was thinking of starting to work on a BSP crate for nucleo-f767zi to get my feet wet.

and the BSP/example repos for that particular family

Is there a loose standard of what a BSP is in this community? Based on other repos, it looks like they are examples + off chip drivers (e.g. LEDs) + debug support? I think this makes sense, matches the CMSIS Pack ecosystem (DFP is basically PAC + HAL). However there are also board-specific examples in the HAL repositories as well...? I wonder if things could be more organized if there was just one repo per device family. Multiple crates could still be published for HAL + various BSPs, but keeping it in one repo might help with long term maintainability?

stm32f7xx/
    examples/
        board1/
        board2/
        ...
    src/
        hal/
            gpio.rs
        board1/
            led.rs
        ...

Maybe there is a good reason different repos are used that I'm overlooking!

[therealprof]

Maybe the moniker BSP is a bit over-ambitious. 🤔 It is not super-trivial and obvious how to construct a real BSP in Rust.

One reason they're separate is that we don't want to maintain a ton of oh-so-slightly different examples for different boards; if they live in the same crate they always have to use the latest and greatest version which can result in a huge maintenance overhead especially with breaking changes we have now and then.

If someone manages to come up with a good abstraction I could totally see a single BSP crate (and examples) for all known boards instead of a ton of copy-and-paste separate BSPs.

[bbrown1867]

That's a good point - if there was a way to have a set of common examples for a HAL that were easily runnable on some set of boards, that would be ideal.

Looking more into BSPs in this project, they are quite thin and are mostly just examples. I think a supported, released BSP probably only adds a lot of value when the board has many off-chip components.

[Sh3Rm4n]

I'm in favor of a more structurally organized organization. At least I'd think that guidelines, like these written up in the OP, and better communication channels (like this repo) could help the stm32-rs organization to better align with their goals.

Better defined goals could also lower the barrier of current maintainers backing up unmaintained HALs or help to acquire new maintainers across the organization.