diff --git a/docs/1.0-release.md b/docs/1.0-release.md
new file mode 100644
index 0000000000..565e1910b6
--- /dev/null
+++ b/docs/1.0-release.md
@@ -0,0 +1,40 @@
+# HTTPX 1.0
+
+The `httpx` 1.0 release includes a number of API changes intended to present a simpler, more consistent interface throughout.
+
+If you're migrating from previous versions, you'll need to be aware of the following:
+
+## Simplified transport configuration
+
+* The `verify` and `cert` arguments no longer exist. Use `ssl_context = httpx.SSLContext(verify=..., cert=...)` instead. See [the SSL documentation](#) for details.
+* The `http1` and `http2` arguments no longer exist. Use `version = httpx.Version("HTTP/1.1", "HTTP/2")` instead. See [the HTTP version documentation](#) for details.
+* The `proxies` argument no longer exists. Use `proxy = httpx.Proxy(...)` instead. See [the Proxy documentation](#) for details.
+* The `retries`, `local_address`, `socket_options`, and `uds` arguments no longer exist. Use `network_options = httpx.NetworkOptions(...)` instead. See [the Network Options documentation](#) for details.
+* The `app = ...` shortcut no longer exists. Use `transport = httpx.WSGITransport()` or `transport = httpx.ASGITransport()` instead. See [the Transport documentation](#) for details.
+* The `mounts = ...` argument no longer exists. Use `transport = httpx.Mounts()` or `transport = httpx.AsyncMounts()` instead. See [the Transport documentation](#) for details.
+* The `trust_env` argument no longer exists, and no environment variables are used by default. See the "Environment Variables" section below for more details.
+
+## Stricter parameters
+
+* The `auth = <callable>` and `auth = (username, password)` shortcuts are no longer supported. Use an explict auth class instead, such as `auth = httpx.BasicAuth(username, password)`.
+* The `timeout = <float|None>` shortcut is no longer supported. Use an explicit `timeout = httpx.Timeout(...)` configuration instead. To disable timeouts use an explicit `timeout = httpx.Timeout(None)`.
+* The `proxy = <str>` shortcut is no longer supported. Use an explicit `proxy = httpx.Proxy(...)` configuration instead.
+
+## Minor cleanups
+
+* All components on `httpx.URL` instances now return `str` ...
+
+* The `Response.elapsed` property no longer exists. Usage of event hooks can provide this functionality if required. See [the Event Hooks](documentation) for details.
+
+## Environment variables
+
+* The `SSL_CERT_FILE`, `SSL_CERT_DIR` and `SSLKEYLOGFILE` environment variables are no longer automatically used, See [the SSL documentation](#) for details one how apply them.
+* `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` and `NO_PROXY` are no longer automatically used. Use `transport = httpx.Mount(use_proxy_env=True)` or `transport = httpx.AsyncMount(use_proxy_env=True)` 
+
+## Dependencies
+
+* `httpx` now has a lighter dependancy install footprint, and does not install the async variant by default. Use `pip install "httpx[asyncio]"` or `pip install "httpx[trio]"` for async support.
+
+## Versioning
+
+* From `1.0` onwards, `httpx` can be expected to follow the [SEMVER versioning policy](#).
\ No newline at end of file