From 4e77ff41193363a6f6a5c87a44d224094f71dc72 Mon Sep 17 00:00:00 2001
From: Martin Algesten <martin@algesten.se>
Date: Thu, 26 Sep 2024 19:34:39 +0200
Subject: [PATCH] Write migration doc

---
 MIGRATE-2-to-3.md | 52 +++++++++++++++++++++++++++++++++++++++--------
 README.md         |  2 ++
 README.tpl        |  2 ++
 3 files changed, 48 insertions(+), 8 deletions(-)

diff --git a/MIGRATE-2-to-3.md b/MIGRATE-2-to-3.md
index 8b6df3a4..b23dcc66 100644
--- a/MIGRATE-2-to-3.md
+++ b/MIGRATE-2-to-3.md
@@ -1,12 +1,48 @@
+# Changes ureq 2.x -> 3.x
+
+This is not an exhaustive list of changes. Most tweaks to the API are clear by looking
+at the docs. If anything is unclear, please open a PR and we can clarify further.
+
+## HTTP Crate
+
+In 2.x ureq implemented it's own `Request` and `Response` structs. In 3.x, we
+drop our own impl in favor of the [http crate]. The http crate presents a unified HTTP
+API and can be found as a dependency of a number of big [http-related crates] in the
+Rust ecosystem. The idea is that presenting a well-known API towards users of ureq
+will make it easier to use.
 
 * .set -> .header
-* 2.x charset feature controled lossy vs encoding_rs.
+
+```
+// ureq2.x
+ureq::get("https://httpbin.org/get").set("foo", "bar").call();
+// ureq3.x
+ureq::get("https://httpbin.org/get").header("foo", "bar").call();
+```
+
+## Re-exported crates must be semver 1.x (stable)
+
+ureq2.x re-exported a number of semver 0.x crates and thus suffered from that breaking
+changes in those crates technically were breaking changes in ureq (and thus ought to increase
+major version). In ureq 3.x we will strive to re-export as few crates as possible.
+
 * No re-exported tls config
-* No re-exported cookie API
+* No re-exported cookie crates
 * No re-exported json macro
-* into_string() -> read_to_string()
-* native-certs is gone. native roots are always available.
-* lossy utf-8 always enabled also when not charset feature
-* agent builder
-* no retry idempotent (for now)
-* no send body charset encoding (for now)
+
+Instead we made our own TLS config and Cookie API, and drop the json macro.
+
+
+
+## No retry idempotent
+
+ureq 2.x did an automatic retry of idempotent methods (GET, HEAD). This was considered
+confusing, so 3.x has no built-in retries.
+
+## No send body charset
+
+For now, ureq 3.x can't change the charset of a send body. It can however still do that
+for the response body.
+
+[http crate]         : https://crates.io/crates/http
+[http-related crates]: https://crates.io/crates/http/reverse_dependencies
diff --git a/README.md b/README.md
index 415758cf..d661add8 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,8 @@
 In anticipation of releasig ureq 3.x, the main branch is now the 3.x version. The current
 main released version is in the [2.x](https://github.com/algesten/ureq/tree/2.x) branch.
 
+[Read our migration doc][MIGRATE-2-to-3.md]
+
 ---
 
 # ureq
diff --git a/README.tpl b/README.tpl
index fcd96414..1730fbe8 100644
--- a/README.tpl
+++ b/README.tpl
@@ -5,6 +5,8 @@
 In anticipation of releasig ureq 3.x, the main branch is now the 3.x version. The current
 main released version is in the [2.x](https://github.com/algesten/ureq/tree/2.x) branch.
 
+[Read our migration doc][MIGRATE-2-to-3.md]
+
 ---
 
 # {{crate}}