Prepare for release 0.1.0

[algesten]

We're going to keep str0m as a workspace, and release subcrates that are not actually stand-alone crates. They are not intended to be used by others and come with a qualifying warning:

//! This crate is an internal detail of [str0m](https://crates.io/crates/str0m).
//!
//! No guarantees are made about the stability of the API. Do not use.

• str0m-dtls
• str0m-ice
• str0m-net
• str0m-packet
• str0m-rtp
• str0m-sctp
• str0m-sdp

Furthermore the intention is to forever keep them on version numbers 0.0.x, to indicate they are internal details, not full releases. I.e. even when str0m man crate graduates to 1.0.0, we keep the sub-crates on 0.0.x.

The only documentation that matters is that of str0m, the doc is a combo of re-exports and local items.

The best way I found to view the doc that will be in the release, is to:

1. cd <workspace top>
2. cargo clean
3. (cd str0m && cargo doc --no-deps --open)

[thomaseizinger]

It is exciting to see this being released soon! Over at rust-libp2p, we have a large workspace too. This sentence struck my attention and I figured I may have some interesting things to share:

Furthermore the intention is to forever keep them on version numbers 0.0.x, to indicate they are internal details, not full releases. I.e. even when str0m man crate graduates to 1.0.0, we keep the sub-crates on 0.0.x.

I'd advise caution here. If you keep your sub-crates forever on 0.0.x, cargo essentially treats them as x.0.0, in other words, it won't automatically upgrade between releases. I assume this is what you want?

Also, if you re-export items from sub-crates, they become your public API. A breaking change in a sub-crate is a breaking change in your root crate, regardless of what your documentation says.

Putting this together means that once you hit 1.0.0, all re-exported items from your sub-crates are essentially also 1.0.0. You can somewhat circumvent this by wrapping all types and not re-exporting your dependencies

If you don't actually care about your sub-crates, you could also just pack everything into a single crate and simply feature-flag that one heavily for the individual modules.

I can also recommend looking into https://github.com/obi1kenobi/cargo-semver-checks. It is still early days but there are quite a few useful checks already.

[algesten]

If you don't actually care about your sub-crates, you could also just pack everything into a single crate and simply feature-flag that one heavily for the individual modules.

Thanks for that input! Very good to know. I didn't know the 0.0.x-strategy was such a bad idea (😅). However, I've been leaning towards merging everything into one crate anyway. I do like my subcrates for development and sanity, but ultimately the project is going to have one facade on crates.io, so that is the overriding concern.

[thomaseizinger]

I do like my subcrates for development and sanity

There are multiple benefits to having sub-crates:

1. cargo can compile them in parallel
2. You can issue patch releases for specific units of code

I guess what I want to say is: Have sub-crates if you like but semver them accordingly.

but ultimately the project is going to have one facade on crates.io

We have one facade crate too (libp2p). The reason we have all the sub-crates is because some of them are "interface" crates that allow users to plug in their custom behaviour without having to depend on everything for that.

For WebRTC, I guess that isn't really much of a concern because it is pretty much specified and not as customizable?

Going from one to many crates (assuming clean module boundaries) isn't that hard so if I may, my advise would be: Start with one crate and split it into several once you run into problems. I've started reshuffle some crate boundaries because they turned out to not be what we need and it is difficult once they are in-place: libp2p/rust-libp2p#3271

[algesten]

@thomaseizinger thanks!

I will merge this PR just to get the documentation fixes into main. Will do a follow-up PR with a reorg of the crate most likely merging all sub-crates into one crate.