Futures-rs: Yank futures 0.2?

[seanmonstar]

Since futures 0.2 is considered just a snapshot that libraries shouldn't expose, most of the ecosystem is still using futures 0.1. It is not expected that 0.2 will see any more development, nor that the ecosystem will move to it. Instead, work is ongoing to try to get futures into libstd.

However, the version on crates.io is 0.2, and the version that is shown on docs.rs is also 0.2. This leads to a lot of confusion when new users try to get started in the ecosystem, since they don't understand why futures returned by libraries don't implement futures::Future (from v2) (example).

Could it just be yanked/deprecated/etc, with a 0.1.22 published to get the docs.rs and crates.io listings to suggest 0.1 until the new version is actually ready?

[djc]

Yes, please! Another problem I noticed yesterday is that the playground offers tokio-0.1 and futures-0.2, which of course don't really work together.

[aturon]

The 0.2 release was, I believe, a mistake. I personally am open to yanking it for the reasons you mention; @cramertj, how do you feel?

One concern: we're getting close to a 0.3-alpha, which I think will cause similar problems (but we need to publish it to allow crates.io crates to use it behind a flag). Anybody have ideas about that?

[seanmonstar]

While 0.3 is nightly-only, could it just be futures-nightly or something?

[aturon]

@seanmonstar that seems plausible (and has some other advantages), but we'd have to do that for the full set of crates, not just the top-level one. Still, that might be the best option.

Right now it sounds like Fuchsia is relying on 0.2 on crates.io and yanking would be a headache. But I wonder if we could take the same approach there...? (In practice that's not much different from the status quo with distinct branches anyway).

[Thomasdezeeuw]

I'm also using v0.2, could we atleast wait until v0.3 is released? This way I can just move to v0.3 rather then going back to v0.1 and move to v0.3 again.

[olix0r]

I have to admit, I've been caught several times looking at the wrong versions of the documentation. It's pretty confusing/jarring when methods in the docs don't exist on the crate... Perhaps this is a docs.rs UI issue, though.

[seanmonstar]

Not to sound presumptuous, if I'm wrong, then I'm wrong! But if it would help more people to yank, can we prioritize helping the larger group? futures 0.2 could be republished maybe to futures-preview, and 0.3 could go there too?

[aturon]

@seanmonstar Yeah that's basically what I have in mind at this point also. @cramertj, how's that sound?

[MajorBreakfast]

Here's what I suggest:

• Publish all futures crate versions under futures: 0.1.x and 0.2.x and 0.3.x. Semver ensures that everyone gets the desired version because 0.x releases are considered major releases.
• Link to the docs of all versions in the README on the the git master branch: The docs for 0.1 are accessible under https://docs.rs/futures/0.1.19/futures/ The links just need better exposure
• As soon as futures 0.3 is ready for alpha put it on the master branch. master should always be the branch where development is happening. Currently only half of 0.3 is working, so it makes sense to not put on master just yet.

This has the following consequences:

• 0.3 is available as the futures crate from the get go. There's no futures-preview crate. No switching. This makes the 0.3 branch discoverable and it's critical that many people start using once it's ready. We need many users. The stuff that was put into libcore needs serious battle testing before stabilization. We need to be sure that there's nothing in it that we would regret putting in later.
• Everyone on 0.1.x and 0.2.x has proper access to the docs
• No need to publish under multiple crate names

[carllerche]

@MajorBreakfast the problem is that everyone learning & using Tokio, Hyper, etc... goes to https://docs.rs/futures and doesn't realize that it is a different futures version. This is causing significant confusion in the ecosystem. We are getting regular issue reports & confusion in IRC / gitter. Your proposal does not address this problem.

[seanmonstar]

@MajorBreakfast I don't think the issue people are running into is about finding links to the correct version. It's that if you try to use the larger ecosystem at the moment, and see "oh I need to add the futures crate", you go to https://crates.io/crates/futures and just copy the latest version. That right there causes very confusing compiler errors about how something like FutureResult<Foo> doesn't implement Future.

Additionally, every time those working in the ecosystem want to look at the docs, they likely just type https://docs.rs/futures in their browser, and click around, and then get confused why when they try to use methods they just read about, they don't exist.

[MajorBreakfast]

@carllerche Yes that's a problem. Here's an idea: How about a message on top of the landing page:

futures 0.3 is currently in preview

Running Tokio or Hyper? Visit docs for futures 0.1.

We'd need to use a //! comment so that it is expanded by default. What do you think?

[Nemo157]

Could 0.2 be yanked and re-released as 0.2.*-preview or something? That will still make it available for the current users of it, but should highlight that it's not intended for general consumption yet. I'm not sure how crates.io or docs.rs handle pre-release versions, but hopefully they will show the latest non-pre-release as the default version?

[carllerche]

Is there consensus re: plan of action?

[aturon]

@carllerche Waiting to hear from @cramertj on this.

[cramertj]

I'm fine with yanking 0.2 so long as it's first re-published under a different name and I'm given time to migrate. I would also be okay with yanking it entirely once enough time has passed that I've been able to migrate to 0.3-alpha (a few weeks out?)

[carllerche]

@cramertj IMO futures as a crate name should be avoided until a release that will have some sort of "long term" support.

edit: Isn't futures 0.3 nightly only?

[cramertj]

@carllerche Yes, I agree-- I think both should be under a futures-nightly or futures-unstable crate prefix.

[pietroalbini]

Can we please avoid yanking crates if not strictly necessary? Yanking futures 0.2 will break every crate depending on it on crater.

[DoumanAsh]

While I find it very annoying to get problems due to incompatibility of alpha futures with 0.1 I think it is a bit late yo yank the whole preview branch without at least having some alternative.

P.s. I hope it should be a good lesson to not release alpha versions as stable

[MajorBreakfast]

I think not-yanking crates should be general policy. It is important that one can depend on the future availability of the crates that one decides to use in a project. Everyone should be able to agree on this.
In particular high-profile crates where members of the core team are involved in the development should follow this practice. Yanking should only be a serious option if there is for instance a legal dispute.

It is important to not leave the people who adopted 0.2 swiftly stranded. I think it is great that there are people who made moving to the newest version a priority. We want swift adoption for 0.3 as well. Discouraging swift adoption by yanking crates is not a good idea.

[lnicola]

@MajorBreakfast

Am I missing something? Yanking a crate doesn't make it go away, it just hides it from the search results and dependency resolution. If you're using a crate and it gets yanked, your project still compiles and works fine.

Right now, people keep running into issues trying to use futures 0.2 with crates that are on 0.1 -- a lot of them. And with 0.3 coming, there's no reason to encourage anyone to use 0.2.

[pietroalbini]

Am I missing something? Yanking a crate doesn't make it go away, it just hides it from the search results and dependency resolution. If you're using a crate and it gets yanked, your project still compiles and works fine.

Yeah, until you need to regenerate the lockfile. Then your only option is to update to another version, because there is no flag allowing you to resolve yanked crates.

[MajorBreakfast]

@lnicola I indeed wrote this thinking that "yank" means complete removal. I've since read up on it. Thx for pointing this out.

What @pietroalbini says seems to me to be nevertheless still a rather big problem. In particular early adopters would still be punished for adopting early.

The problem with re-releasing it under another crate name is that all crates would need to switch to this different crate. The two Future traits would not be compatible with each other.

[carllerche]

@aturon do you have an ETA for this?

[ngg]

Hi!
We have an internal project in our company that already switched to 0.2, currently we use the master branch because the released version does not compile with the "nightly" feature enabled and we use the async/await support. When we switched to 0.2 we had no way of knowing this is not a good idea.
What would you recommend me to do? Should we switch back to using 0.1 and the futures-await crate? I'd like to avoid this if possible. I think (or hope) a usable 0.3 version will be ready soon, but until then we kind of need a working 0.2. I am pretty sure that if it would be yanked then no one will fix possible further breakages caused by nightly compiler updates.

[seanmonstar]

I don't believe 0.2 will be seeing any more development, and as you said, "we had no way of knowing this is not a good idea", I suspect leaving 0.2 as the current version on crates.io will continue to cause problems like these.

[ngg]

I'm not saying it's a good idea to leave it there or not, I'm just saying we're one of those early adapters you're talking about. We already have to use the git version because of the "nightly" feature but I think there might be lots of projects sticking to the released version (it's perfectly working with the default features). If you decide to yank it then please continue the current master branch as 0.2, and please fix or accept PRs to fix the compiler errors at least until a 0.3.0-alpha release.

[aturon]

ETA to publish-and-yank is tonight, @cramertj plans to tackle it.

@ngg yes, we'll ensure there are ways to work with 0.2 in the interim as well; you're not the only one who needs it! But @seanmonstar and others are correct that the status quo is very confusing, and in hindsight the DOA "snapshot" release was a misstep.

[carllerche]

@aturon Thanks for the info!

[cramertj]

I've opened #1048 which moves the current 0.2 crates over to "-preview"-suffixed forms. Once that's published, I'll yank 0.2.0 and 0.2.1, leaving 0.1 as the current long-term-supported version.

When 0.3 is ready (nightly-only), I'll publish it under the "-preview"-suffixed form as well, giving us time to experiment and make any necessary changes. Once 0.3 and the std::future::Future API have stabilized, we can move 0.3 (or whatever follows) over to the long-term-support channel.

Thanks for all your patience while we sort this out!

[seanmonstar]

Hurray!

As of right now, 0.2.0 and 0.2.1 aren't yanked yet. And I suspect that after they are, a 0.1.22 needs to be published to upgrade the crates.io and docs.rs pages. Should we keep this open until that happens?

[cramertj]

@seanmonstar Sure thing! I'll close once everything is appropriately pushed and yanked.

[cramertj]

I've yanked 0.2.0-alpha through 0.2.1, which leaves 0.1.21 as the latest release of the futures crate. futures-preview has been published as 0.2.2.

https://users.rust-lang.org/t/futures-0-2-has-been-moved-to-futures-preview/18329

[seanmonstar]

Looks like crates.io is updated, but https://docs.rs/futures still chooses to forward to the 0.2.1 version (I tried with a cleared cache, but I could still be wrong...)

[cramertj]

@seanmonstar Darn it! Thanks for the heads-up. I left a comment here: https://github.com/onur/docs.rs/issues/112#issuecomment-400483934