Add guide for upgrading to the new asyncio implementation.

docs/howto/index.rst

@@ -8,6 +8,14 @@ In a hurry? Check out these examples.
 
    quickstart
 
+Upgrading from the legacy :mod:`asyncio` implementation to the new one?
+Read this.
+
+.. toctree::
+   :titlesonly:
+
+   upgrade
+
 If you're stuck, perhaps you'll find the answer here.
 
 .. toctree::

docs/project/changelog.rst

@@ -25,6 +25,8 @@ fixing regressions shortly after a release.
 Only documented APIs are public. Undocumented, private APIs may change without
 notice.
 
+.. _13.0:
+
 13.0
 ----
 
@@ -66,10 +68,10 @@ New features
 
     This new implementation is intended to be a drop-in replacement for the
     current implementation. It will become the default in a future release.
-    Please try it and report any issue that you encounter!
 
-    See :func:`websockets.asyncio.client.connect` and
-    :func:`websockets.asyncio.server.serve` for details.
+    Please try it and report any issue that you encounter! The :doc:`upgrade
+    guide <../howto/upgrade>` explains everything you need to know about the
+    upgrade process.
 
 * Validated compatibility with Python 3.12 and 3.13.
 
@@ -79,6 +81,8 @@ New features
   If you were monkey-patching constants, be aware that they were renamed, which
   will break your configuration. You must switch to the environment variables.
 
+.. _12.0:
+
 12.0
 ----
 
@@ -135,6 +139,8 @@ Bug fixes
 
 * Restored the C extension in the source distribution.
 
+.. _11.0:
+
 11.0
 ----
 
@@ -211,6 +217,8 @@ Improvements
 * Set ``server_hostname`` automatically on TLS connections when providing a
   ``sock`` argument to :func:`~sync.client.connect`.
 
+.. _10.4:
+
 10.4
 ----
 
@@ -237,6 +245,8 @@ Improvements
 
 * Improved FAQ.
 
+.. _10.3:
+
 10.3
 ----
 
@@ -259,6 +269,8 @@ Improvements
 
 * Reduced noise in logs when :mod:`ssl` or :mod:`zlib` raise exceptions.
 
+.. _10.2:
+
 10.2
 ----
 
@@ -279,6 +291,8 @@ Bug fixes
 
 * Avoided leaking open sockets when :func:`~client.connect` is canceled.
 
+.. _10.1:
+
 10.1
 ----
 
@@ -328,6 +342,8 @@ Bug fixes
 
 * Avoided half-closing TCP connections that are already closed.
 
+.. _10.0:
+
 10.0
 ----
 
@@ -434,6 +450,8 @@ Bug fixes
 
 * Avoided a crash when receiving a ping while the connection is closing.
 
+.. _9.1:
+
 9.1
 ---
 
@@ -472,6 +490,8 @@ Bug fixes
 
 * Fixed issues with the packaging of the 9.0 release.
 
+.. _9.0:
+
 9.0
 ---
 
@@ -549,6 +569,8 @@ Bug fixes
 * Ensured cancellation always propagates, even on Python versions where
   :exc:`~asyncio.CancelledError` inherits :exc:`Exception`.
 
+.. _8.1:
+
 8.1
 ---
 
@@ -583,6 +605,8 @@ Bug fixes
 * Restored the ability to import ``WebSocketProtocolError`` from
   ``websockets``.
 
+.. _8.0:
+
 8.0
 ---
 
@@ -692,6 +716,8 @@ Bug fixes
 
 * Avoided a crash when a ``extra_headers`` callable returns :obj:`None`.
 
+.. _7.0:
+
 7.0
 ---
 
@@ -786,6 +812,8 @@ Bug fixes
   :meth:`~legacy.protocol.WebSocketCommonProtocol.recv`:
   canceling it at the wrong time could result in messages being dropped.
 
+.. _6.0:
+
 6.0
 ---
 
@@ -840,6 +868,8 @@ Bug fixes
 * Fixed a regression in 5.0 that broke some invocations of
   :func:`~server.serve` and :func:`~client.connect`.
 
+.. _5.0:
+
 5.0
 ---
 
@@ -925,6 +955,8 @@ Bug fixes
 
 * Fixed issues with the packaging of the 4.0 release.
 
+.. _4.0:
+
 4.0
 ---
 
@@ -984,6 +1016,8 @@ Bug fixes
 * Stopped leaking pending tasks when :meth:`~asyncio.Task.cancel` is called on
   a connection while it's being closed.
 
+.. _3.4:
+
 3.4
 ---
 
@@ -1027,6 +1061,8 @@ Bug fixes
 * Providing a ``sock`` argument to :func:`~client.connect` no longer
   crashes.
 
+.. _3.3:
+
 3.3
 ---
 
@@ -1047,6 +1083,8 @@ Bug fixes
 
 * Avoided crashing on concurrent writes on slow connections.
 
+.. _3.2:
+
 3.2
 ---
 
@@ -1063,6 +1101,8 @@ Improvements
 
 * Made server shutdown more robust.
 
+.. _3.1:
+
 3.1
 ---
 
@@ -1078,6 +1118,8 @@ Bug fixes
 
 * Avoided a warning when closing a connection before the opening handshake.
 
+.. _3.0:
+
 3.0
 ---
 
@@ -1135,6 +1177,8 @@ Improvements
 
 * Improved documentation.
 
+.. _2.7:
+
 2.7
 ---
 
@@ -1150,6 +1194,8 @@ Improvements
 
 * Refreshed documentation.
 
+.. _2.6:
+
 2.6
 ---
 
@@ -1167,6 +1213,8 @@ Bug fixes
 
 * Avoided TCP fragmentation of small frames.
 
+.. _2.5:
+
 2.5
 ---
 
@@ -1200,6 +1248,8 @@ Bug fixes
 * Canceling :meth:`~legacy.protocol.WebSocketCommonProtocol.recv` no longer
   drops the next message.
 
+.. _2.4:
+
 2.4
 ---
 
@@ -1213,6 +1263,8 @@ New features
 * Added ``loop`` argument to :func:`~client.connect` and
   :func:`~server.serve`.
 
+.. _2.3:
+
 2.3
 ---
 
@@ -1223,6 +1275,8 @@ Improvements
 
 * Improved compliance of close codes.
 
+.. _2.2:
+
 2.2
 ---
 
@@ -1233,6 +1287,8 @@ New features
 
 * Added support for limiting message size.
 
+.. _2.1:
+
 2.1
 ---
 
@@ -1247,6 +1303,8 @@ New features
 
 .. _Origin: https://www.rfc-editor.org/rfc/rfc6455.html#section-10.2
 
+.. _2.0:
+
 2.0
 ---
 
@@ -1275,6 +1333,8 @@ New features
 
 * Added flow control for outgoing data.
 
+.. _1.0:
+
 1.0
 ---
 

docs/reference/asyncio/client.rst

@@ -1,5 +1,5 @@
-Client (:mod:`asyncio`)
-=======================
+Client (legacy :mod:`asyncio`)
+==============================
 
 .. automodule:: websockets.client
 

docs/reference/asyncio/common.rst

@@ -1,7 +1,7 @@
 :orphan:
 
-Both sides (:mod:`asyncio`)
-===========================
+Both sides (legacy :mod:`asyncio`)
+==================================
 
 .. automodule:: websockets.legacy.protocol
 

docs/reference/asyncio/server.rst

@@ -1,15 +1,15 @@
-Server (:mod:`asyncio`)
-=======================
+Server (legacy :mod:`asyncio`)
+==============================
 
 .. automodule:: websockets.server
 
 Starting a server
 -----------------
 
-.. autofunction:: serve(ws_handler, host=None, port=None, *, create_protocol=None, logger=None, compression="deflate", origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header="Python/x.y.z websockets/X.Y", process_request=None, select_subprotocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, **kwds)
+.. autofunction:: serve(ws_handler, host=None, port=None, *, create_protocol=None, logger=None, compression="deflate", origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header="Python/x.y.z websockets/X.Y", process_request=None, select_subprotocol=None, open_timeout=10, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, **kwds)
     :async:
 
-.. autofunction:: unix_serve(ws_handler, path=None, *, create_protocol=None, logger=None, compression="deflate", origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header="Python/x.y.z websockets/X.Y", process_request=None, select_subprotocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, **kwds)
+.. autofunction:: unix_serve(ws_handler, path=None, *, create_protocol=None, logger=None, compression="deflate", origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header="Python/x.y.z websockets/X.Y", process_request=None, select_subprotocol=None, open_timeout=10, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, **kwds)
     :async:
 
 Stopping a server
@@ -34,7 +34,7 @@ Stopping a server
 Using a connection
 ------------------
 
-.. autoclass:: WebSocketServerProtocol(ws_handler, ws_server, *, logger=None, origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header="Python/x.y.z websockets/X.Y", process_request=None, select_subprotocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16)
+.. autoclass:: WebSocketServerProtocol(ws_handler, ws_server, *, logger=None, origins=None, extensions=None, subprotocols=None, extra_headers=None, server_header="Python/x.y.z websockets/X.Y", process_request=None, select_subprotocol=None, open_timeout=10, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16)
 
     .. automethod:: recv
 

docs/reference/new-asyncio/client.rst

@@ -1,5 +1,5 @@
-Client (:mod:`asyncio` - new)
-=============================
+Client (new :mod:`asyncio`)
+===========================
 
 .. automodule:: websockets.asyncio.client
 

docs/reference/new-asyncio/common.rst

@@ -1,7 +1,7 @@
 :orphan:
 
-Both sides (:mod:`asyncio` - new)
-=================================
+Both sides (new :mod:`asyncio`)
+===============================
 
 .. automodule:: websockets.asyncio.connection
 

docs/reference/new-asyncio/server.rst

@@ -1,5 +1,5 @@
-Server (:mod:`asyncio` - new)
-=============================
+Server (new :mod:`asyncio`)
+===========================
 
 .. automodule:: websockets.asyncio.server
 

docs/spelling_wordlist.txt

@@ -21,8 +21,8 @@ cryptocurrency
 css
 ctrl
 deserialize
-django
 dev
+django
 Dockerfile
 dyno
 formatter
@@ -44,6 +44,7 @@ linkerd
 liveness
 lookups
 MiB
+middleware
 mutex
 mypy
 nginx
@@ -77,8 +78,8 @@ uple
 uvicorn
 uvloop
 virtualenv
-WebSocket
 websocket
+WebSocket
 websockets
 ws
 wsgi