Alpha note, and recommendations on pinning versions (#590)

diff --git a/docs/index.md b/docs/index.md
index c233494c926871c053d7808708a5225d15270dc0..746ed59cbc03b9f21071b3369ec0097ab567ea4e 100644 (file)
--- a/docs/index.md
+++ b/docs/index.md
@@ -30,9 +30,16 @@ It can be used in high-performance async web frameworks, using either asyncio
 or trio, and is able to support making large numbers of concurrent requests.
 
 !!! note
-    The 0.8 release switched HTTPX into focusing exclusively on providing an async
-    client. It is possible that we'll look at re-introducing a sync API at a
-    later date.
+    HTTPX should currently be considered in alpha. We'd love early users and feedback,
+    but would strongly recommend pinning your dependencies to the latest median
+    release, so that you're able to properly review API changes between package
+    updates. Currently you should be using `http==0.8.*`.
+
+    In particular, the 0.8 release switched HTTPX into focusing exclusively on
+    providing an async client, in order to move the project forward, and help
+    us [change our approach to providing sync+async support][sync-support]. If
+    you have been using the sync client, you may want to pin to `http==0.7.*`,
+    and wait until our sync client is reintroduced.
 
 ---
 
@@ -123,3 +130,5 @@ $ pip install httpx
 ```
 
 HTTPX requires Python 3.6+
+
+[sync-support]: https://github.com/encode/httpx/issues/572