bytecodealliance / rustix

Safe Rust bindings to POSIX-ish APIs
Other
1.5k stars 161 forks source link

1.0 release planning #753

Open sunfishcode opened 1 year ago

sunfishcode commented 1 year ago

Here's a planning issue for a 1.0 release, similar to the one for the 0.38 release. Hopefully we won't need a semver bump for a good long while, but when we do, here's the list of changes we can make:

notgull commented 1 year ago

It would be nice to have an uninitialized buffer API for read, recv, recvmsg, etc. That way you could read to completely uninitialized buffers.

sunfishcode commented 1 year ago

Reading into uninitialized buffers is tracked in https://github.com/bytecodealliance/rustix/issues/81.

sunfishcode commented 1 year ago

I think it makes sense to call the next release 1.0, instead of 0.39.

0.x version numbers are sometimes seen as signifying instability. And, 0.x version numbers don't have an equivalent of minor versions.

The overall plan here can stay the same. 1.0 (formerly 0.39 here) would still be a good long while after 0.38, and a good long while after that would be a 2.0 (instead of a 0.40), and so on.

notgull commented 1 year ago

If this is going to be a stable release, we should make sure that libc and linux-raw-sys aren't exposed in the public API. I know there are still a few places where it is.

In my opinion a stable release is a bad idea, as the API is still somewhat volatile. There should at least be an "unstable" feature flag to test new APIs for inclusion, like Tokio has.

sunfishcode commented 1 year ago

I already consider 0.38 to be stable. For example, I maintain an older version of linux-raw-sys to preserve compatibility with rustix 0.38. And I'm not aware of any significant volatility in the 0.38 API. It's added lots of features, and even deprecated a handful of things, but ideas for breaking changes are collected here in this issue, specifically to keep 0.38 stable.

So my idea for 1.0 is just to better communicate what's already happening.

It would be nice to better encapsulate libc/linux-raw-sys types, and I'm open to adding an "unstable" feature flag if there's a need for it. I'm under the impression that these aren't urgent right now, though I'd be happy to learn more about how these impact users.

SUPERCILEX commented 11 months ago

rustix::cstr! should be removed now that c"..." strings just went stable: https://github.com/rust-lang/rust/pull/117472

morr0ne commented 11 months ago

rustix::cstr! should be removed now that c"..." strings just went stable: rust-lang/rust#117472

This feature will not be available in stable until February 2024, so we probably want to wait for that.

sunfishcode commented 10 months ago

Rustix's MSRV won't support new features like c"..." strings for quite some time, so we'll need to keep cstr! for now.

SUPERCILEX commented 9 months ago

I'd like to propose making the timeout param in https://docs.rs/rustix/latest/rustix/event/fn.poll.html be an Option<u32> where None passes -1 to act as an infinite timeout. That feels like a clearer interface than anything negative is infinity.

SUPERCILEX commented 3 months ago

Thoughts on pulling a wgpu? https://github.com/gfx-rs/wgpu/releases/tag/v22.0.0 Instead of 1.0 we go straight to 39.0 to make it clear that rustix will keep breaking things as the APIs evolve.

sunfishcode commented 3 months ago

Calling it 1.0 doesn't imply that there won't be a 2.0, so I think we can call it 1.0 and keep our options open for future API changes. That said, rustix is used in enough places that it's worth aiming to preserve a relatively long cadence between API breaks. My sense is that calling it 1.0 communicates that aim better, compared to calling it 39.0.

SUPERCILEX commented 3 months ago

Fair enough.


From https://github.com/bytecodealliance/rustix/pull/1105#discussion_r1718681864, let's add to the todo list that we need to fix the occurrences of cargo clippy --workspace --all-targets --features all-apis -- -Aclippy::all -Dclippy::impl_trait_in_params (and use-libc).

SUPERCILEX commented 3 months ago

From https://github.com/bytecodealliance/rustix/pull/1110#discussion_r1719029848: epoll appears to be inconsistent in that it expects users to use the module prefix (i.e. epoll::foo) instead of using the free function directly. This is neat, but it's inconsistent with the rest of rustix's APIs: inotify, port, eventfd, iouring, mount, shm, and probably others I didn't have time to look at. @sunfishcode thoughts on a PR that restores the `epoll` prefix with some deprecations? We could go the other direction, but that interacts poorly with auto-complete and would be much more breaking so not worth it IMO.

Sidenote: the deprecations won't actually work due to https://github.com/rust-lang/rust/issues/30827. (For example the fs::*mount APIs are deprecated but there's no warning about it.)

sunfishcode commented 2 months ago

I've now created the 0.38 branch and have started doing 0.38.x releases from it, so the main branch can now start accepting semver-incompatible fixes. First up is porting the 1.0-staging patches.

raftario commented 2 months ago

Is there anything you could use outside help with as part of the effort towards a 1.0 release ?

sunfishcode commented 2 months ago

@raftario Anyone's welcome to work on any of the items from the checklist at the top here that isn't checked and doesn't have a PR next to it. Some of them are involved, but some are just simple renames.

sunfishcode commented 2 months ago

Also, anything with a question mark is known to need further thought.