Release notes for 0.21.0

CHANGES.rst

@@ -1,11 +1,11 @@
 Changes
 =======
 
-Unreleased
-----------
+0.21.0 (2024-07-DD)
+-------------------
 
-* The precedence of session param settings, request metadata keys and session
-  config override methods has changed.
+* **Backward-incompatible change:** The precedence of session param settings,
+  request metadata keys and session config override methods has changed.
 
   Before, priority from higher to lower was:
 
@@ -35,6 +35,19 @@ Unreleased
 
   #.  :meth:`~scrapy_zyte_api.SessionConfig.params`
 
+* When using the :reqmeta:`zyte_api_session_params` or
+  :reqmeta:`zyte_api_session_location` request metadata keys, a different pool
+  ID is now generated by default based on their value. See
+  :meth:`~scrapy_zyte_api.SessionConfig.pool` for details.
+
+* The new :reqmeta:`zyte_api_session_pool` request metadata key allows
+  overriding the pool ID of a request.
+
+* Added :ref:`pool management documentation <session-pools>`.
+
+* Fixed some documentation examples where the parameters of the ``check``
+  method of :setting:`ZYTE_API_SESSION_CHECKER` were in reverse order.
+
 
 0.20.0 (2024-06-26)
 -------------------

scrapy_zyte_api/_session.py

@@ -276,20 +276,20 @@ def location(self, request: Request) -> Dict[str, str]:
         keys as described in :ref:`session-init`.
 
         When overriding this method, you should only return a custom value if
-        the default implementation returns an empty :class:`dict`, to avoid
-        breaking the :ref:`precedence chain that users expect <session-init>`,
-        e.g.
+        the default implementation returns an empty :class:`dict`, e.g.
 
         .. code-block:: python
 
             def location(self, request: Request) -> Dict[str, str]:
                 fallback = {"addressCountry": "US", "addressRegion": "NY", "postalCode": "10001"}
                 return super().location(request) or fallback
 
-        .. note:: An implementation of :meth:`~scrapy_zyte_api.SessionConfig.location`
-            can technically override :reqmeta:`zyte_api_session_location` or
-            :setting:`ZYTE_API_SESSION_LOCATION`, but it is not recommended as it
-            breaks the precedence chain above that users may expect.
+        .. note:: An implementation of
+            :meth:`~scrapy_zyte_api.SessionConfig.location` can technically
+            override :reqmeta:`zyte_api_session_location` or
+            :setting:`ZYTE_API_SESSION_LOCATION`, but it is not recommended as
+            it breaks the :ref:`precedence chain that users expect
+            <session-init>`.
 
         You should only override this method if you need a location to be
         used even when no location is specified through request metadata or