Proper versioning and publishing on crates.io?

[gendx]

In the review of https://github.com/tock/libtock-rs/pull/103 (changing the API to Rust's futures), the topic of breaking changes was brought up.

Given that:

• this library is mature enough to build standalone applications (e.g. https://github.com/tock/libtock-rs/pull/92),
• moving to a future-based API would be quite a breaking change,

I think that introducing proper versioning would make sense for libtock-rs. It doesn't have to be stable (https://github.com/tock/libtock-rs/issues/62), we can use unstable versions (0.x) until it's agreed that libtock-rs is stable enough.

Adding a CHANGELOG.md would also make sense to document large changes such as moving to futures or supporting a new version of the kernel, so that external users are not surprised by a sudden breaking change in a commit.

Additionally, I think that it would make sense to publish libtock-rs on crates.io, to make it easier for external projects to depend on (it's a library after all). As a precedent, https://github.com/tock/tock/tree/master/libraries/tock-register-interface is published on crates.io, and the process to publish crates is quite smooth.

[Woyten]

Just to give you an impression why I think libtock-rs is far from being stable: https://github.com/tock/libtock-rs/pull/103#discussion_r346571393

[gendx]

Replying here as I think it makes more sense in a separate issue than in a sub-thread of a specific pull-request.

So, what would you propose as a practical solution? I am asking because we still plan a lot of breaking changes. A few examples:

The practical solution that I propose is to add versioning to mark points where such breaking changes arrive. And a changelog with roughly one line per breaking change. It doesn't have to be more than that. I think it's independent from stabilization, as the semantic versioning used in Rust is clear about the fact that code versioned as 0.x is unstable.

I think that versioning + publishing on crates.io can make it easier for users to experiment on top of libtock-rs, and therefore give feedback, contribute to it, etc. This doesn't have to wait for a perfect libtock-rs. Despite the current limitations, I think that libtock-rs is already usable for more than simple examples, which is good :)

• Not all drivers are checked for availability => There should be an init() for every driver
• The drivers can be used at any position in the code => There must be a global Runtime struct which controls sharing of drivers
• There are unwraps() all around the code base => All drivers should return a meaningful result
• The result should contain information about the failed driver => All syscalls must return a TockError or something else
• The callbacks are hard to use. They must not be moved, so they need to be passed in from outside by &mut => They should not be used. Futures are better and don't have ownership problems

This is probably one of the trickiest points. As we've seen with https://github.com/tock/tock/pull/1376, Tock's handling of callbacks can be somewhat confusing and brittle, so I just want to make sure that futures don't have similar problems (ala "use-after-free" of the underlying callback).

That being said, when I first tried libtock-rs, I was very confused by the fact that launching an alarm and then spinning in a loop wouldn't trigger the alarm, as the app has to explicitly yield. So if futures can help with the ergonomics here (by hiding the yield), it's a good thing (as long as it doesn't lead to further confusion).

• All drivers work in a different way => They should work in the same way

And so on. libtock currently is a collection of small experiments. Stability would be a great. But to achieve this goal, I can only encourage everyone to put feedback on the design document. Then, we can implement the design and, after that, we can make a commitment on stability.

As I mentioned above, there's no commitment to be made on stability by publishing 0.x.y versions. Just incrementing the x number whenever a breaking change happens. But multiple breaking changes could be batched in one version, it doesn't have to be a regular publishing schedule, etc. I just think that the current API would make sense for a 0.1, and that the future-based runtime would make sense as a 0.2 (or something like that).

Regarding the design document, where is it? I've been experimenting with libtock-rs for months but it's the first time I hear about it, as it's not linked anywhere in the README. I don't see it either on https://github.com/tock/libtock-rs/issues/62. Adding a link to it in the README would be very helpful for new users (and future contributors) of libtock-rs.

[torfmaster]

@gendx: We started writing a design document in https://github.com/tock/libtock-rs/pull/20 some time ago. As we didn't come to a consensus we didn't merge it, yet. 👍 for adding this to the readme and finalizing (parts of) it.

[gendx]

Thanks for pointing out https://github.com/tock/libtock-rs/pull/20, that's really helpful!