Graceful upgrade path for 0.28

Author: tomchristie

CHANGELOG.md

@@ -6,13 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
-This release introduces an `httpx.SSLContext()` class and `ssl_context` parameter.
+The 0.28 release includes a limited set of backwards incompatible changes.
 
-* Added `httpx.SSLContext` class and `ssl_context` parameter. (#3022, #3335)
-* The `verify` and `cert` arguments have been deprecated and will now raise warnings. (#3022, #3335)
+**Backwards incompatible changes**:
+
+SSL configuration has been significantly simplified.
+
+* The `verify` argument no longer accepts string arguments.
+* The `cert` argument has now been removed.
+* The `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables are no longer automatically used.
+
+For users of the standard `verify=True` or `verify=False` cases this should require no changes.
+
+For information on configuring more complex SSL cases, please see the [SSL documentation](docs/advanced/ssl.md).
+
+**The following changes are also included**:
+
+* The undocumented `URL.raw` property has now been deprecated, and will raise warnings.
 * The deprecated `proxies` argument has now been removed.
 * The deprecated `app` argument has now been removed.
-* The `URL.raw` property has now been removed.
 * Ensure JSON request bodies are compact. (#3363)
 * Review URL percent escape sets, based on WHATWG spec. (#3371, #3373)
 * Ensure `certifi` and `httpcore` are only imported if required. (#3377)