v2.0 upgrade path

[benesch]

First of all, thanks for maintaining this crate! Maintaining an open source project can be thankless work, and especially so when it's a foundational crate like this one.

I recently embarked on upgrading reqwest to url v2.0 (seanmonstar/reqwest#583), and ran into some roadblocks. These roadblocks would have been greatly eased if this crate maintained a changelog or release notes. (If it does, and I've just missed it, apologies! But it's awfully hard to find in that case.) It's very hard to figure out what's changed when upgrading across backwards-incompatible changes without a changelog.

The commit messages don't do a great job of explaining rationale, either. Here's a quick example: fe74a60. Why were the public exports of percent_encoding removed? It's no longer clear to me how to ensure that the version of percent_encoding I'm using matches the version used by url. I poked at the PR description (#517), too, and it's no more helpful in explaining the rationale. There's a brief mention of the work item in the 2.0 tracking issue (#463), but again doesn't present rationale.

The upgrade guide for 0.1 -> 1.0, by contrast, is fantastic! I'd like to put one together for 1.0 -> 2.0, but I'll need some help to do so.

Some other issues that could use explaining:

• percent_encoding no longer exports useful character classes. I had to dig through closed issues to find the rationale for this: Export PATH_SEGMENT and other percent encoding AsciiSets #529;
• the removal of ToSocketAddr, which is also explained in a closed issue: std::net::ToSocketAddrs dropped from 2.0.0 #530.

I'd also like to specifically gripe about the removal of ToSocketAddr. I've now reimplemented that code poorly—because I wasn't sure how to do it properly—twice [0] [1] and @SimonSapin reimplemented it at least once [0]. If we figure out a way to provide with_default_port with less API surface, can we bring it back?

[SimonSapin]

how to ensure that the version of percent_encoding I'm using matches the version used by url

Can you say more about why that’s important? I feel that it’s more important that a future breaking change in percent_encoding API would not cause a breaking change in libraries that have a public dependency on url but do not use percent encoding functionality.

percent_encoding no longer exports useful character classes

Useful to do what? Were they (in 1.x) really the appropriate ones for your use case?

[benesch]

how to ensure that the version of percent_encoding I'm using matches the version used by url

Can you say more about why that’s important? I feel that it’s more important that a future breaking change in percent_encoding API would not cause a breaking change in libraries that have a public dependency on url but do not use percent encoding functionality.

Perhaps it's not? I was vaguely worried that something like reqwest could see strange skew because it uses url to perform percent encoding in some places, but uses percent_encoding in other places.

Most of my concern stemmed from the fact that it seemed like url was intentionally exporting percent_encoding in 1.0 because it was important that you be able to upgrade your percent_encoding and url deps in lockstep. I see now that is not actually the case; rather percent_encoding was extracted from url and the re-export existed for backwards compatibility. (Right?)

Anyway, seems perfectly reasonable to have them decoupled. My concern here is totally solved with the upgrade guide!

percent_encoding no longer exports useful character classes

Useful to do what? Were they (in 1.x) really the appropriate ones for your use case?

Well, cookie was using USERINFO_ENCODE_SET (https://github.com/SergioBenitez/cookie-rs/pull/122/files#diff-b4aea3e418ccdb71239b96952d9cddb6R84). Full disclosure, though: I haven't checked for sure if that's actually the right thing to do. And reqwest was using PATH_SEGMENT_ENCODE_SET (https://github.com/seanmonstar/reqwest/pull/583/files#diff-a3e784467561f56f7fc664d81007a5e0R374-R380) in its multipart implementation.

[DoumanAsh]

@SimonSapin In all honestly I believe that you should re-export your dependencies for user to access it so that both would use the same version without need to manually check which version one should use.

[SimonSapin]

@benesch I’m hoping this removal will be a nudge to check if that’s the right thing to do.

@DoumanAsh I very much disagree, for the reason given above.