seanmonstar

hyper Polish Period

A couple weeks ago, we announced the first release candidate of hyper 1.0. hyper is a protective and efficient HTTP library for all, written in the Rust programming language.

I’m calling the time period between the first release candidate and the final release the “hyper polish period”.

Areas of Polish

The main thrust is to polish the edges, and make the final release of hyper 1.0 as smooth as possible for all. It’s still quite a lot to do, and several of the areas will actively benefit from a mixture of experience helping out. It seems there’s four main areas of work to do, so we need a few things from the community:

• Folks to volunteer to “lead” an area.¹
• Anyone to pick a task from an area and work on it.
• Try to use the release candidates, and give us feedback.

How about some more details about each area.

Area: Docs

hyper should have stellar documentation, all around. We should be an example for all Rust crates on how to have top-notch documentation. Caring about the documentation is caring about the developer experience. They are our users. They should be delighted whenever trying to do something new with hyper. Certainly, there will always be ways to improve them. But that doesn’t mean we can’t try to make them awesome for the 1.0 launch.

The API documentation needs to better rounded out. Behavior should be explained here, a user shouldn’t need to go read a guide to understand if a type has a certain behavior.

The website, hyper.rs, can be improved to better accomplish its various purposes. The examples from the repository could be rendered on the website. The docs folder containing internal documentation could be rendered as a “contrib” section. It could be easier to find the blog (and we could use that more).

While guides are technically part of the website, I view them to be sufficiently big enough to consider separately. We could use a more in-depth guide using more of hyper, perhaps slowly building on pieces from previous guides. WIth so many useful pieces now in hyper-util, guides should help show how to include and use them. We can also add a Tower section, showing the power of adding Tower middleware to your server of client.

Area: Utils

Many of the less stable, higher level parts of hyper 0.14.x have been removed, with the promise of most showing back up in hyper-util. Some of these are very simple ports. Others will be made more generic or configurable, encouraging users to plug and play on top of it all.

For example, consider the previous hyper::Client . It combined many concepts together for the convenience of users: a mechanism to establish new connections, a pool to store idle connections for a period of time, and a way for the connector to signal to the pool if HTTP/2 was negotiated via ALPN. You could only customize those pieces if specific options were part of the client Builder. As part of the move to hyper-util, the way those pieces plug together can be made public.² That does likely mean more work on our part though.

Area: Upgrading

We want as smooth of an upgrade as possible.

The smoothest would be if there were only types or methods being removed. Then we could just add deprecations in 0.14.x, and the compiler would help people prepare early. But, when an upgrade involves changes to methods, or behavior, it’s more complicated.³ Still, the more we can do to make things easier, the better!

As described in the upgrade meta issue, we can backport some of the new additions, and we can use #[deprecated] to guide people to start using better stuff earlier.

We can only backport additions, since that won’t break code. We can’t backport removals, or changes. In some ways, this work is on the easier side, since it’s not solving new problems. It’s taking copying working code from the release candidate, and pasting it into the 0.14.x branch. Likely some internal types or methods have changed names.

It does mean in some cases including significantly more code, so we’ll make the backports opt-in with a Cargo feature flag.

Once some of the new APIs are backported, we can add deprecation messages to the things they are meant to replacing. They can include a link back to a specific issue describing the motivation and anything else they need to consider about the change.

There are other parts of that are removed completely, without a replacement in core hyper. It seems like it would be useful to let people start preparing for their disappearance. Each deprecation warning can point to its own issue, explaining what the user could do instead, perhaps changing the pattern they use, or copying the code of what’s in hyper-util.

I don’t expect everyone to upgrade to 1.0 as soon as it comes out, so having the compiler help people to be more ready and make their eventual upgrade smoother has significant value. It helps earn the trust of our users, hopefully reducing upgrade fear for future releases.

Area: Integration Feedback

The release candidate period is principally to allow for gathering of feedback about any further breaking changes that should be considered before stabilizing.

Some users have already tried out the release candidate, and filed issues of things we need to address. But we can’t simply assume that if no one complains, people like it. More often, if someone doesn’t like something, they just quietly use something else entirely.

We also can’t assume people will even try it out on their own during this time period.

So, we’ll want to actively engage people with different use cases, help them try to upgrade, and record their feedback ourselves. The more reports we can gather, the better. I also have a simple list of people at big companies, start-ups, and hobbyists that I’ll be sure to check in with.

If you’re able to help give the feedback, we recognize the time and effort to do so as a valuable contribution towards the hyper project. The project and community are made better because of you, so thank you!

This may also reveal changes that would be good to make in hyper-util. But releases there are easy. The most urgent part of this area is to make sure we take care of all necessary breaking changes in hyper core, before calling it 1.0.

Join us!

We expect this polish period to last a couple of months. There’s a lot to do, and a lot of places for people of all sorts to join in and make this release awesome.

Check out the boards, implement something cool, write a guide, give us feedback, backport something, volunteer to own (or co-own) an area. You can make a big difference for users of Rust’s HTTP libraries.

1.0, here we come!