Crate Versioning

[Rahix]

As avr-hal is made up of quite a few crates, decision needs to be made how versioning is handled. The two extremes would be

1. All crates are versioned in lock-step and interdependencies are listed as =X.Y.Z to enforce the lock-step versioning.
2. Releases and versions are managed on a per-crate basis.

Option 1. has the obvious drawback that a breaking change in any crate would lead to a major version bump for all crates. OTOH, Option 2. would mean a lot of effort to ensure no errors are made and any crate needing an update gets it. Especially breaking changes in the generic part are difficult to manage here ...

At first glance, I'm not a fan of either of those. Maybe there is some middle-ground that is acceptable?

[explicite]

First option will suffer from this drawback only when we will publish generic part to frequent. Like now with #77 we want to move to new hal. For users will be easier to use first one. I will vote for for first option too.

[Rahix]

First option will suffer from this drawback only when we will publish generic part to frequent.

Actually, I think it is the other way around: when updating avr-hal-generic, it makes sense to bump all the other crates as well. But when e.g. doing a change in arduino-leonardo, lock-step versioning would mean all other crates will get a version bump, too, even though nothing changed.

That's still somewhat acceptable for minor version bumps (semver-compatible), but for example when doing a breaking change in arduino-leonardo, this would mean a semver-incompatible bump for all other crates as well ... That's what I dislike about it.

[explicite]

Maybe will be worth to do features as in https://github.com/Rahix/avr-device ? The other way will be split generic to another repo. Maybe you can share why we have such design now. Will be easier to understand for me and provide some help.

[Beanow]

It's definitely non-trivial and don't know if I can give you a straight recommendation. But at least some notes.

Independent versioning can certainly be done, but comes with error prone busywork. Do consider some amount of automation. For ESP it seems to be manual https://github.com/esp-rs/esp-hal/issues/800 and STM mostly leans on cargo publish as well https://github.com/search?q=org%3Astm32-rs+publish+language%3AMarkdown&type=code&l=Markdown

At Tauri we've been using https://github.com/jbolda/covector, example configs. It comes with a process to get used to, but certainly makes option 2 more palatable.

---

In terms of versions themselves, avoid 0.0.x releases and start with the 0.1.0 as cargo init does or go straight to 1.0.0. Sooner or later you'll wish you could do a patch release. Better to use README to communicate stability/maintenance status. (Though alpha/beta/rc semver does work well when contrasted with normal releases.)

---

Finally, I would say it helps to think about audiences when deciding on this. For example:

• As an avr-hal maintainer
• As an #embedded-hal-driver maintainer
• As a developer of a greenfield project
• As a developer of a brownfield project

Because it can frame the tradeoffs better.

For instance, maybe you would prefer more breaking changes in the setup code for brownfield projects, if that buys you decent stability on drivers and faster releases on new boards or embedded-hal breaking changes.