Add a changelog and an upgrade guide for v2.0.

Fix servo#532.

CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to the url package will be documented in this file.
+
+Changes to the other packages in this project can be found in their respective
+directories:
+
+  * [data-url](data-url/CHANGELOG.md)
+  * [idna](idna/CHANGELOG.md)
+  * [percent-encoding](percent_encoding/CHANGELOG.md)
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2019-07-23
+
+### Changed
+
+* The minimum supported Rust version is now v1.33.0 ([#510], [`9ab946f34`],
+  and [#517]).
+
+* Serde has been bumped to v1.x ([#512]).
+
+* Exhaustive matching of `url::ParseError` and `url::SyntaxError` is now
+  discouraged via a hidden enum variant ([#525]), so that adding additional
+  variants in the future will not be considered a breaking change.
+
+### Removed
+
+* `url::Url` no longer implements `std::net::ToSocketAddrs` ([`6e0820148`]),
+  and the related method `with_default_port` and type `HostAndPort` have been
+  removed as well. The implementation of these features introduced a large
+  amount of API surface area and was not considered to be a core competency of
+  the project.
+
+* The `idna` and `percent_export` crates are no longer exported by the `url`
+  crate, so that breaking changes to those crates do not constitute a breaking
+  change to the `url` crate ([`fe74a60bd`]).
+
+* `_charset_` support ([`47e2286ff`]). TODO: say more.
+
+* `rust-encoding` support ([`b567a51e7`]). TODO: say more.
+
+* rustc-serialize is no longer supported. Specifically, the `rustc-serialize`
+  feature has been removed, and so it is no longer possible to configure
+  `url::Url` to implement the `rustc_serialize::Encodable` and
+  `rustc_serialize::Decodable` traits ([#507]). rustc-serialize is deprecated,
+  and Serde has been stable for over two years.
+
+* The `heapsize` feature has been removed, as the [heapsize] project is no
+  longer maintained ([`394e63a75`]).
+
+* The `url_serde` crate is no longer maintained, as the `url` crate now ships
+  support for Serde 1.x (when the `serde` feature is enabled) ([`51d6b33f7`]).
+
+### Fixed
+
+* Domains that have trailing hyphens are no longer incorrectly rejected
+  ([#484]).
+
+## 1.7.2 - 2018-07-06
+
+The changelog was not maintained for v1.7.2 and earlier.
+
+[Unreleased]: https://github.com/servo/rust-url/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/servo/rust-url/compare/v1.7.2...v2.0.0
+
+[#484]: https://github.com/servo/rust-url/pull/484
+[#507]: https://github.com/servo/rust-url/pull/507
+[#510]: https://github.com/servo/rust-url/pull/510
+[#512]: https://github.com/servo/rust-url/pull/512
+[#517]: https://github.com/servo/rust-url/pull/517
+[#525]: https://github.com/servo/rust-url/pull/525
+
+[`394e63a75`]: https://github.com/servo/rust-url/commit/394e63a7518e1bfe8e106ebc7938706b10cfa1aa
+[`47e2286ff`]: https://github.com/servo/rust-url/commit/47e2286ff32359879e69651409ed08385949eb8c
+[`51d6b33f7`]: https://github.com/servo/rust-url/commit/51d6b33f717d29880cb53a1f5bf0d061d846ad35
+[`6e0820148`]: https://github.com/servo/rust-url/commit/6e082014827061a79a27be1d7712e53a84c28280
+[`9ab946f34`]: https://github.com/servo/rust-url/commit/9ab946f3419ed14142227e9e1dfea9bbb6ac5c17
+[`b567a51e7`]: https://github.com/servo/rust-url/commit/b567a51e784bae1fdad1d1e5d7e4dcb00b406080
+[`fe74a60bd`]: https://github.com/servo/rust-url/commit/fe74a60bd0636c5e5da920674b9bbffc22f3c384
+
+[heapsize]: https://github.com/servo/heapsize

UPGRADING.md

@@ -1,4 +1,113 @@
-# Guide to upgrading from url 0.x to 1.x
+# Upgrade guide
+
+This guide contains steps for upgrading crates in this project between major
+versions. Only the most common issues are covered here. For full details of
+changes, see the [changelog](CHANGELOG.md).
+
+## Upgrading from url 1.x to 2.x
+
+* The minimum supported Rust version is now v1.33.0. Verify that you can bump
+  your library or application to the same MSRV.
+
+* `Url` no longer implements `std::net::ToSocketAddrs`. You will instead need to
+  explicitly convert your `Url` to a type that implements `ToSocketAddrs`.
+
+    Before upgrading:
+
+    ```rust
+    let url = Url::parse("http://github.com:80").unwrap();
+    let stream = TcpStream::connect(url).unwrap();
+    ```
+
+    After upgrading:
+
+    ```rust
+    let url = Url::parse("http://github.com:80").unwrap();
+    let port = url.port_or_known_default().unwrap();
+    let addrs;
+    let addr;
+    let addrs = match url.host().unwrap() {
+        url::Host::Domain(domain) => {
+            addrs = (domain, port).to_socket_addrs().unwrap();
+            addrs.as_slice()
+        }
+        url::Host::Ipv4(ip) => {
+            addr = (ip, port).into();
+            std::slice::from_ref(&addr)
+        }
+        url::Host::Ipv6(ip) => {
+            addr = (ip, port).into();
+            std::slice::from_ref(&addr)
+        }
+    };
+    let stream = TcpStream::connect(addrs).unwrap();
+    ```
+
+* `url_serde` is no longer required to use `Url` with Serde 1.x. Remove
+  references to `url_serde` and enable the `serde` feature instead.
+
+     ```toml
+     # Cargo.toml
+     [dependencies]
+     url = { version = "2.0", features = ["serde"] }
+     ```
+
+* The `idna` and `percent_export` crates are no longer exported by the `url`
+  crate. Depend on those crates directly instead. See below for additional
+  breaking changes in the percent-export package.
+
+    Before upgrading:
+
+    ```rust
+    use url::percent_encoding::percent_decode;
+    ```
+
+    After upgrading:
+
+    ```rust
+    use percent_encoding::percent_decode;
+    ```
+
+## Upgrading from percent-encoding 1.x to 2.x
+
+* Prepackaged encoding sets, like `QUERY_ENCODE_SET` and
+  `PATH_SEGMENT_ENCODE_SET`, are no longer provided. You will need to read You
+  will need to read the specifications relevant to your domain and construct
+  your own encoding sets by using the `percent_encoding::AsciiSet` builder
+  methods on either of the base encoding sets, `percent_encoding::CONTROLS` or
+  `percent_encoding::NON_ALPHANUMERIC`.
+
+    Before upgrading:
+
+    ```rust
+    use percent_encoding::PATH_SEGMENT_ENCODE_SET;
+
+    percent_encoding::utf8_percent_encode(value, PATH_SEGMENT_ENCODE_SET);
+    ```
+
+    After upgrading:
+
+    ```rust
+    /// https://url.spec.whatwg.org/#fragment-percent-encode-set
+    const FRAGMENT_ENCODE_SET: &AsciiSet = &percent_encoding::CONTROLS
+        .add(b' ').add(b'"').add(b'<').add(b'>').add(b'`');
+
+    /// https://url.spec.whatwg.org/#path-percent-encode-set
+    const PATH_ENCODE_SET: &AsciiSet = &FRAGMENT_ENCODE_SET
+        .add(b'#').add(b'?').add(b'{').add(b'}');
+
+    const PATH_SEGMENT_ENCODE_SET: &AsciiSet = &PATH_ENCODE_SET.add(b'/').add(b'%');
+
+    percent_encoding::utf8_percent_encode(value, PATH_SEGMENT_ENCODE_SET);
+    ```
+
+  You can use the [private encoding sets in the URL parser][encoding-sets] as
+  a basis.
+
+  [encoding-sets]: https://github.com/servo/rust-url/blob/f491cb442edab75be54ff5961af6458a474f1f9a/src/parser.rs#L18-L45
+
+
+## Upgrading from url 0.x to 1.x
 
 * The fields of `Url` are now private because the `Url` constructor, parser,
   and setters maintain invariants that could be violated if you were to set the fields directly.

data-url/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to the data-url package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.1.0 - 2018-02-02
+
+The changelog was not maintained for v0.1.0 and earlier.

idna/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to the idna package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.2.0 - 2019-07-23
+
+### Added
+
+* Support for the `CheckHyphens` flag in the domain to ASCII algorithm ([#484]).
+
+* A `domain_to_ascii_strict` function, which runs the domain to ASCII algorithm
+  with the `beStrict` flag set ([`737128608`]).
+
+### Changed
+
+* The algorithms are now configured through a `Config` struct, which
+  can be modified via the builder pattern, rather than by directly passing
+  a flags struct to the implicated functions ([#484]).
+
+### Removed
+
+* The `uts46` module is private. The relevant structs within are re-exported at
+  the top level ([`5aeaf89af`]).
+
+## 0.1.5 - 2018-07-06
+
+The changelog was not maintained for v0.1.5 and earlier.
+
+[#484]: https://github.com/servo/rust-url/pull/484
+
+[`5aeaf89af`]: https://github.com/servo/rust-url/commit/5aeaf89afe43c78eef7c958b1089bd586f68c271
+[`737128608`]: https://github.com/servo/rust-url/commit/7371286087b32d358610df1ad3a3b1f55f6836df

percent_encoding/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to the percent-encoding package will be documented in this
+file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 2.0.0 - 2019-07-23
+
+### Changed
+
+* Encoding sets are now values of a new `percent_encoding::AsciiSet` type,
+  rather than any type that implements `percent_encoding::EncodeSet` ([#519]).
+  This fixes a longstanding bug where `EncodeSet`s could not be boxed ([#388]).
+  The `EncodeSet` trait has accordingly been removed.
+
+* The prepackaged encoding sets, like `percent_encoding::QUERY_ENCODE_SET` and
+  `percent_encoding::PATH_SEGMENT_ENCODE_SET`, have been removed ([#519]).
+  Instead, read the specifications relevant to your domain and construct your
+  own encoding sets by using the `percent_encoding::AsciiSet` builder methods
+  on either of the base encoding sets, `percent_encoding::CONTROLS` or
+  `percent_encoding::NON_ALPHANUMERIC`.
+
+## 1.0.1 - 2017-11-11
+
+The changelog was not maintained for v1.0.1 and earlier.
+
+[#388]: https://github.com/servo/rust-url/issues/388
+[#519]: https://github.com/servo/rust-url/pull/619