search

ringbahn / uring-sys

liburing bindings
Apache License 2.0
33 stars 14 forks source link

Long term versioning story #11

Open withoutboats opened 5 years ago

withoutboats commented 5 years ago

I would like to version this exactly like liburing - release the first non-prerelease version at 1.0.3 linked to the commit that is liburing's 0.3 release. liburing has a strong backwards compatibility story (axboe/liburing#34) so in an ideal world that would be fine.

However, C allows certain patterns that liburing takes advantage of, which cannot be replicated in Rust as a non-breaking change. In particular, I'm thinking of unions inside of structs. Liburing can add a new field which overlaps with another by turning the old field into a union. For example, it did this by chaning the __u64 off; field of io_uring_sqe into union { __u64 off; __u64 addr2; }.

Rust cannot emulate this, and we are required to replace the field with a new union type (which is why Rust's io_uring_sqe has a type called off_addr2).

Can't think of a perfect solution to handle this. Options I can think of are:

  1. Make a major version bump if this ever happens.
  2. Put at least some of the structs under some sort of unstable feature flag.
  3. Just allow the breaking change in a minor version on the hope it won't impact anyone.
quininer commented 4 years ago

You can generate getter/setter for union members and avoid internal structure leaks. This should be sufficient to ensure that API stable.

withoutboats commented 4 years ago

Yea, especially since these structs are not being constructed by users (and therefore don't need gnarly constructors) I was thinking making the fields private and providing getters/setters was the best solution

withoutboats commented 4 years ago

It's become clear in more recent releases that liburing will keep modifying struct definitions based on C's flexibility. At the same time, these types appear in the public API of libraries like iou. It would be great to update #13 to the current version of uring-sys, so we can start versioning this 1.X and not make updating to new versions of liburing a breaking change for libraries like iou.