Repository: urllib3/urllib3

Issue:
Write a Migration Guide for v1.26.x -> v2.0.0
Can be a part of the v2.0.0 Roadmap documentation. Would be good to detail the specific steps and causes of all DeprecationWarnings and be URL-linkable so we can point to these docs within the actual warnings.

Discussion:
illia-v: Just a reminder that we do not want to include changes backported to 1.26.x in the changelog of 2.0.0 🙂
sethmlarson: @illia-v Thanks for the reminder, I think I've gone through and gotten most of the ones we did end up backporting, do you see any that I missed?
pquentin: I think we should add entries for the following changes too:

 * https://github.com/urllib3/urllib3/pull/2571
 * https://github.com/urllib3/urllib3/pull/2529
 * https://github.com/urllib3/urllib3/pull/2537
 * https://github.com/urllib3/urllib3/pull/2348
 * https://github.com/urllib3/urllib3/pull/2482
 * https://github.com/urllib3/urllib3/pull/2452
 * https://github.com/urllib3/urllib3/pull/2434
 * https://github.com/urllib3/urllib3/pull/2241
sethmlarson: I've integrated the PRs that you found @pquentin

Had no user facing changes:
- https://github.com/urllib3/urllib3/pull/2529
- https://github.com/urllib3/urllib3/pull/2241 (since it wasn't released, technically not a fix?)

Patch:
diff --git a/CHANGES.rst b/CHANGES.rst
index c7d85a7f..ae556f46 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -1,3 +1,124 @@
+2.0.0a1 (2022-11-15)
+====================
+
+Read the `v2.0 migration guide <https://urllib3.readthedocs.io/en/latest/v2-migration-guide.html>`__ for help upgrading to the latest version of urllib3.
+
+Added
+-----
+
+* Added type hints to the ``urllib3`` module (`#1897 <https://github.com/urllib3/urllib3/issues/1897>`__).
+* Added ``ssl_minimum_version`` and ``ssl_maximum_version`` options which set
+  ``SSLContext.minimum_version`` and ``SSLContext.maximum_version`` (`#2110 <https://github.com/urllib3/urllib3/issues/2110>`__).
+* Added support for Zstandard (RFC 8878) when ``zstandard`` 1.18.0 or later is installed.
+  Added the ``zstd`` extra which installs the ``zstandard`` package (`#1992 <https://github.com/urllib3/urllib3/issues/1992>`__).
+* Added ``urllib3.response.BaseHTTPResponse`` class. All future response classes will be subclasses of ``BaseHTTPResponse`` (`#2083 <https://github.com/urllib3/urllib3/issues/2083>`__).
+* Added top-level ``urllib3.request`` function which uses a preconfigured module-global ``PoolManager`` instance (`#2150 <https://github.com/urllib3/urllib3/issues/2150>`__).
+* Added ``FullPoolError`` which is raised when ``PoolManager(block=True)`` and a connection is returned to a full pool (`#2197 <https://github.com/urllib3/urllib3/issues/2197>`__).
+* Added ``HTTPHeaderDict`` to the top-level ``urllib3`` namespace (`#2216 <https://github.com/urllib3/urllib3/issues/2216>`__).
+* Added the ``json`` parameter to ``urllib3.request()``, ``PoolManager.request()``, and ``ConnectionPool.request()`` methods to send JSON bodies in requests. Using this parameter will set the header ``Content-Type: application/json`` if ``Content-Type`` isn't already defined.
+  Added support for parsing JSON response bodies with ``HTTPResponse.json()`` method (`#2243 <https://github.com/urllib3/urllib3/issues/2243>`__).
+* Added support for configuring header merging behavior with HTTPHeaderDict
+  When using a ``HTTPHeaderDict`` to provide headers for a request, by default duplicate
+  header values will be repeated. But if ``combine=True`` is passed into a call to
+  ``HTTPHeaderDict.add``, then the added header value will be merged in with an existing
+  value into a comma-separated list (``X-My-Header: foo, bar``) (`#2242 <https://github.com/urllib3/urllib3/issues/2242>`__).
+* Added ``NameResolutionError`` exception when a DNS error occurs (`#2305 <https://github.com/urllib3/urllib3/issues/2305>`__).
+* Added ``proxy_assert_hostname`` and ``proxy_assert_fingerprint`` kwargs to ``ProxyManager`` (`#2409 <https://github.com/urllib3/urllib3/issues/2409>`__).
+* Added a configurable ``backoff_max`` parameter to the ``Retry`` class.
+  If a custom ``backoff_max`` is provided to the ``Retry`` class, it
+  will replace the ``Retry.DEFAULT_BACKOFF_MAX`` (`#2494 <https://github.com/urllib3/urllib3/issues/2494>`__).
+* Added the ``authority`` property to the Url class as per RFC 3986 3.2. This property should be used in place of ``netloc`` for users who want to include the userinfo (auth) component of the URI (`#2520 <https://github.com/urllib3/urllib3/issues/2520>`__).
+* Added the ``scheme`` parameter to ``HTTPConnection.set_tunnel`` to configure the scheme of the origin being tunnelled to (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+* Added the ``is_closed``, ``is_connected`` and ``has_connected_to_proxy`` properties to ``HTTPConnection`` (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+
+Removed
+-------
+
+* Removed support for Python 2.7, 3.5, and 3.6 (`#883 <https://github.com/urllib3/urllib3/issues/883>`__, `#2336 <https://github.com/urllib3/urllib3/issues/2336>`__).
+* Removed fallback on certificate ``commonName`` in ``match_hostname()`` function.
+  This behavior was deprecated in May 2000 in RFC 2818. Instead only ``subjectAltName``
+  is used to verify the hostname by default. To enable verifying the hostname against
+  ``commonName`` use ``SSLContext.hostname_checks_common_name = True`` (`#2113 <https://github.com/urllib3/urllib3/issues/2113>`__).
+* Removed support for Python with an ``ssl`` module compiled with LibreSSL, CiscoSSL,
+  wolfSSL, and all other OpenSSL alternatives. Python is moving to require OpenSSL with PEP 644 (`#2168 <https://github.com/urllib3/urllib3/issues/2168>`__).
+* Removed support for OpenSSL versions earlier than 1.1.1 or that don't have SNI support.
+  When an incompatible OpenSSL version is detected an ``ImportError`` is raised (`#2168 <https://github.com/urllib3/urllib3/issues/2168>`__).
+* Removed the list of default ciphers for OpenSSL 1.1.1+ and SecureTransport as their own defaults are already secure (`#2082 <https://github.com/urllib3/urllib3/issues/2082>`__).
+* Removed ``urllib3.contrib.appengine.AppEngineManager`` and support for Google App Engine Standard Environment (`#2044 <https://github.com/urllib3/urllib3/issues/2044>`__).
+* Removed deprecated ``Retry`` options ``method_whitelist``, ``DEFAULT_REDIRECT_HEADERS_BLACKLIST`` (`#2086 <https://github.com/urllib3/urllib3/issues/2086>`__).
+* Removed ``urllib3.HTTPResponse.from_httplib`` (`#2648 <https://github.com/urllib3/urllib3/issues/2648>`__).
+* Removed default value of ``None`` for the ``request_context`` parameter of ``urllib3.PoolManager.connection_from_pool_key``. This change should have no effect on users as the default value of ``None`` was an invalid option and was never used (`#1897 <https://github.com/urllib3/urllib3/issues/1897>`__).
+* Removed the ``urllib3.request`` module. ``urllib3.request.RequestMethods`` has been made a private API.
+  This change was made to ensure that ``from urllib3 import request`` imported the top-level ``request()``
+  function instead of the ``urllib3.request`` module (`#2269 <https://github.com/urllib3/urllib3/issues/2269>`__).
+* Removed support for SSLv3.0 from the ``urllib3.contrib.pyopenssl`` even when support is available from the compiled OpenSSL library (`#2233 <https://github.com/urllib3/urllib3/issues/2233>`__).
+* Removed the deprecated ``urllib3.contrib.ntlmpool`` module (`#2339 <https://github.com/urllib3/urllib3/issues/2339>`__).
+* Removed ``DEFAULT_CIPHERS``, ``HAS_SNI``, ``USE_DEFAULT_SSLCONTEXT_CIPHERS``, from the private module ``urllib3.util.ssl_`` (`#2168 <https://github.com/urllib3/urllib3/issues/2168>`__).
+* Removed ``urllib3.exceptions.SNIMissingWarning`` (`#2168 <https://github.com/urllib3/urllib3/issues/2168>`__).
+* Removed the ``_prepare_conn`` method from ``HTTPConnectionPool``. Previously this was only used to call ``HTTPSConnection.set_cert()`` by ``HTTPSConnectionPool`` (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+* Removed ``tls_in_tls_required`` property from ``HTTPSConnection``. This is now determined from the ``scheme`` parameter in ``HTTPConnection.set_tunnel()`` (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+
+Changed
+-------
+
+* Changed ``urllib3.response.HTTPResponse.read`` to respect the semantics of ``io.BufferedIOBase`` regardless of compression. Specifically, this method:
+
+  * Only returns an empty bytes object to indicate EOF (that is, the response has been fully consumed).
+  * Never returns more bytes than requested.
+  * Can issue any number of system calls: zero, one or multiple.
+
+  If you want each ``urllib3.response.HTTPResponse.read`` call to issue a single system call, you need to disable decompression by setting ``decode_content=False`` (`#2128 <https://github.com/urllib3/urllib3/issues/2128>`__).
+* Changed ``ssl_version`` to instead set the corresponding ``SSLContext.minimum_version``
+  and ``SSLContext.maximum_version`` values.  Regardless of ``ssl_version`` passed
+  ``SSLContext`` objects are now constructed using ``ssl.PROTOCOL_TLS_CLIENT`` (`#2110 <https://github.com/urllib3/urllib3/issues/2110>`__).
+* Changed default ``SSLContext.minimum_version`` to be ``TLSVersion.TLSv1_2`` in line with Python 3.10 (`#2373 <https://github.com/urllib3/urllib3/issues/2373>`__).
+* Changed ``ProxyError`` to wrap any connection error (timeout, TLS, DNS) that occurs when connecting to the proxy (`#2482 <https://github.com/urllib3/urllib3/pull/2482>`__).
+* Changed ``urllib3.util.create_urllib3_context`` to not override the system cipher suites with
+  a default value. The new default will be cipher suites configured by the operating system (`#2168 <https://github.com/urllib3/urllib3/issues/2168>`__).
+* Changed ``multipart/form-data`` header parameter formatting matches the WHATWG HTML Standard as of 2021-06-10. Control characters in filenames are no longer percent encoded (`#2257 <https://github.com/urllib3/urllib3/issues/2257>`__).
+* Changed ``urllib3.HTTPConnection.getresponse`` to return an instance of ``urllib3.HTTPResponse`` instead of ``http.client.HTTPResponse`` (`#2648 <https://github.com/urllib3/urllib3/issues/2648>`__).
+* Changed return type of ``HTTPResponse.getheaders()`` method to return a list of key-value tuples to match CPython (`#1543 <https://github.com/urllib3/urllib3/issues/1543>`__).
+* Changed the error raised when connecting via HTTPS when the ``ssl`` module isn't available from ``SSLError`` to ``ImportError`` (`#2589 <https://github.com/urllib3/urllib3/issues/2589>`__).
+* Changed ``HTTPConnection.request()`` to always use lowercase chunk boundaries when sending requests with ``Transfer-Encoding: chunked`` (`#2515 <https://github.com/urllib3/urllib3/issues/2515>`__).
+* Changed `enforce_content_length` default to True, preventing silent data loss when reading streamed responses (`#2514 <https://github.com/urllib3/urllib3/issues/2514>`__).
+* Changed internal implementation of ``HTTPHeaderDict`` to use ``dict`` instead of ``collections.OrderedDict`` for better performance (`#2080 <https://github.com/urllib3/urllib3/issues/2080>`__).
+* Changed the ``urllib3.contrib.pyopenssl`` module to wrap ``OpenSSL.SSL.Error`` with ``ssl.SSLError`` in ``PyOpenSSLContext.load_cert_chain`` (`#2628 <https://github.com/urllib3/urllib3/issues/2628>`__).
+* Changed usage of the deprecated ``socket.error`` to ``OSError`` (`#2120 <https://github.com/urllib3/urllib3/issues/2120>`__).
+* Changed all parameters in the ``HTTPConnection`` and ``HTTPSConnection`` constructors to be keyword-only except ``host`` and ``port`` (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+* Changed ``urllib3.util.is_connection_dropped()`` to use ``HTTPConnection.is_connected`` (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+* Changed ``HTTPConnection.getresponse()`` to set the socket timeout from ``HTTPConnection.timeout`` value before reading
+  data from the socket. This previously was done manually by the ``HTTPConnectionPool`` calling ``HTTPConnection.sock.settimeout(...)`` (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+* Changed the ``_proxy_host`` property to ``_tunnel_host`` in ``HTTPConnectionPool`` to more closely match how the property is used (value in ``HTTPConnection.set_tunnel()``) (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+* Changed name of ``Retry.BACK0FF_MAX`` to be ``Retry.DEFAULT_BACKOFF_MAX``.
+* Changed TLS handshakes to use ``SSLContext.check_hostname`` when possible (`#2452 <https://github.com/urllib3/urllib3/pull/2452>`__).
+* Changed ``server_hostname`` to behave like other parameters only used by ``HTTPSConnectionPool`` (`#2537 <https://github.com/urllib3/urllib3/pull/2537>`__).
+* Changed the default ``blocksize`` to 16KB to match OpenSSL's default read amounts (`#2348 <https://github.com/urllib3/urllib3/pull/2348>`__).
+
+Deprecated
+----------
+
+* Deprecated ``urllib3.contrib.pyopenssl`` module which will be removed in urllib3 v2.1.0 (`#2691 <https://github.com/urllib3/urllib3/issues/2691>`__).
+* Deprecated ``urllib3.contrib.securetransport`` module which will be removed in urllib3 v2.1.0 (`#2692 <https://github.com/urllib3/urllib3/issues/2692>`__).
+* Deprecated ``ssl_version`` option in favor of ``ssl_minimum_version``. ``ssl_version`` will be removed in urllib3 v2.1.0 (`#2110 <https://github.com/urllib3/urllib3/issues/2110>`__).
+* Deprecated the ``strict`` parameter as it's not longer needed in Python 3.x. It will be removed in urllib3 v2.1.0 (`#2267 <https://github.com/urllib3/urllib3/issues/2267>`__)
+* Deprecated the ``NewConnectionError.pool`` attribute which will be removed in urllib3 v2.1.0 (`#2271 <https://github.com/urllib3/urllib3/issues/2271>`__).
+* Deprecated ``format_header_param_html5`` and ``format_header_param`` in favor of ``format_multipart_header_param`` (`#2257 <https://github.com/urllib3/urllib3/issues/2257>`__).
+* Deprecated ``RequestField.header_formatter`` parameter which will be removed in urllib3 v2.1.0 (`#2257 <https://github.com/urllib3/urllib3/issues/2257>`__).
+* Deprecated ``HTTPSConnection.set_cert()`` method. Instead pass parameters to the ``HTTPSConnection`` constructor (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+* Deprecated ``HTTPConnection.request_chunked()`` method which will be removed in urllib3 v2.1.0. Instead pass ``chunked=True`` to ``HTTPConnection.request()`` (`#1985 <https://github.com/urllib3/urllib3/issues/1985>`__).
+
+Fixed
+-----
+
+* Fixed thread-safety issue where accessing a `PoolManager` with many distinct origins would cause connection pools to be closed while requests are in progress (`#1252 <https://github.com/urllib3/urllib3/issues/1252>`__).
+* Fixed an issue where an ``HTTPConnection`` instance would erroneously reuse the socket read timeout value from reading the previous response instead of a newly configured connect timeout.
+  Instead now if ``HTTPConnection.timeout`` is updated before sending the next request the new timeout value will be used (`#2645 <https://github.com/urllib3/urllib3/issues/2645>`__).
+* Fixed ``socket.error.errno`` when raised from pyOpenSSL's ``OpenSSL.SSL.SysCallError`` (`#2118 <https://github.com/urllib3/urllib3/issues/2118>`__).
+* Fixed the default value of ``HTTPSConnection.socket_options`` to match ``HTTPConnection`` (`#2213 <https://github.com/urllib3/urllib3/issues/2213>`__).
+* Fixed a bug where ``headers`` would be modified by the ``remove_headers_on_redirect`` feature (`#2272 <https://github.com/urllib3/urllib3/issues/2272>`__).
+* Fixed a reference cycle bug in ``urllib3.util.connection.create_connection()`` (`#2277 <https://github.com/urllib3/urllib3/issues/2277>`__).
+* Fixed a socket leak if ``HTTPConnection.connect()`` fails (`#2571 <https://github.com/urllib3/urllib3/pull/2571>`__).
+
 1.26.12 (2022-08-22)
 ====================
 
diff --git a/changelog/1252.bugfix.rst b/changelog/1252.bugfix.rst
deleted file mode 100644
index c30f5f12..00000000
--- a/changelog/1252.bugfix.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-Fixed thread-safety issue where accessing a `PoolManager` with many distinct origins
-would cause connection pools to be closed while requests are in progress.
diff --git a/changelog/1543.bugfix.rst b/changelog/1543.bugfix.rst
deleted file mode 100644
index 55591676..00000000
--- a/changelog/1543.bugfix.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Changed return type of ``HTTPResponse.getheaders()`` method to return a list of key-value tuples to match CPython.
\ No newline at end of file
diff --git a/changelog/1897.feature.rst b/changelog/1897.feature.rst
deleted file mode 100644
index aaefd282..00000000
--- a/changelog/1897.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Added type hints to the ``urllib3`` module.
\ No newline at end of file
diff --git a/changelog/1897.removal.rst b/changelog/1897.removal.rst
deleted file mode 100644
index 6ff8a399..00000000
--- a/changelog/1897.removal.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-Removed default value of ``None`` for the ``request_context`` parameter of ``urllib3.PoolManager.connection_from_pool_key``.
-
-This change should have no effect on users as the default value of ``None`` was an invalid option and was never used.
diff --git a/changelog/1985.removal.rst b/changelog/1985.removal.rst
deleted file mode 100644
index 7f7b51b5..00000000
--- a/changelog/1985.removal.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-All changes below are to distance the ``urllib3.connection.HTTPConnection`` API from the standard library ``http.client.HTTPConnection`` API enough to allow future HTTP implementations.
-
-Added the ``scheme`` parameter to ``HTTPConnection.set_tunnel`` to configure the scheme of the origin being tunnelled to.
-
-Added the ``is_closed``, ``is_connected`` and ``has_connected_to_proxy`` properties to ``HTTPConnection``.
-
-Changed all parameters in the ``HTTPConnection`` and ``HTTPSConnection`` constructors to be keyword-only except ``host`` and ``port``.
-
-Changed ``urllib3.util.is_connection_dropped()`` to use ``HTTPConnection.is_connected``.
-
-Changed ``HTTPConnection.getresponse()`` to set the socket timeout from ``HTTPConnection.timeout`` value before reading
-data from the socket. This previously was done manually by the ``HTTPConnectionPool`` calling ``HTTPConnection.sock.settimeout(...)``.
-
-Changed the ``_proxy_host`` property to ``_tunnel_host`` in ``HTTPConnectionPool`` to more closely match how the property is used (value in ``HTTPConnection.set_tunnel()``).
-
-Removed the ``_prepare_conn`` method from ``HTTPConnectionPool``. Previously this was only used to call ``HTTPSConnection.set_cert()`` by ``HTTPSConnectionPool``.
-
-Removed ``tls_in_tls_required`` property from ``HTTPSConnection``. This is now calculated from the ``scheme`` parameter in ``HTTPConnection.set_tunnel()``.
-
-Deprecated ``HTTPSConnection.set_cert()`` method. Instead pass parameters to the ``HTTPSConnection`` constructor.
-
-Deprecated ``HTTPConnection.request_chunked()`` method. Instead pass ``chunked=True`` to ``HTTPConnection.request()``.
diff --git a/changelog/1992.feature.rst b/changelog/1992.feature.rst
deleted file mode 100644
index d2caff5a..00000000
--- a/changelog/1992.feature.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-Added support for Zstandard (RFC 8878) when ``zstandard`` 1.18.0 or later is installed.
-Added the ``zstd`` extra which installs the ``zstandard`` package.
\ No newline at end of file
diff --git a/changelog/2044.removal.rst b/changelog/2044.removal.rst
deleted file mode 100644
index 8dd6324c..00000000
--- a/changelog/2044.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Removed ``urllib3.contrib.appengine.AppEngineManager`` and support for Google App Engine Standard Environment.
\ No newline at end of file
diff --git a/changelog/2080.feature.rst b/changelog/2080.feature.rst
deleted file mode 100644
index ffbab158..00000000
--- a/changelog/2080.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Changed internal implementation of ``HTTPHeaderDict`` to use ``dict`` instead of ``collections.OrderedDict`` for better performance.
\ No newline at end of file
diff --git a/changelog/2082.feature.rst b/changelog/2082.feature.rst
deleted file mode 100644
index c4f827bd..00000000
--- a/changelog/2082.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Stopped configuring default ciphers for OpenSSL 1.1.1+ and SecureTransport as their own defaults are already secure.
\ No newline at end of file
diff --git a/changelog/2083.feature.rst b/changelog/2083.feature.rst
deleted file mode 100644
index 0659121a..00000000
--- a/changelog/2083.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Added ``urllib3.response.BaseHTTPResponse`` class. All future response classes will be subclasses of ``BaseHTTPResponse``.
\ No newline at end of file
diff --git a/changelog/2086.removal.rst b/changelog/2086.removal.rst
deleted file mode 100644
index ed7a087d..00000000
--- a/changelog/2086.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Removed deprecated ``Retry`` options ``method_whitelist``, ``DEFAULT_REDIRECT_HEADERS_BLACKLIST``.
\ No newline at end of file
diff --git a/changelog/2099.feature.rst b/changelog/2099.feature.rst
deleted file mode 100644
index 5d14dd8b..00000000
--- a/changelog/2099.feature.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-Changed ``urllib3[brotli]`` extra to install Google's Brotli C bindings on CPython.
-
-The Brotli CFFI bindings are still used on non-CPython implementations like PyPy.
-This change was made to increase performance for CPython as CFFI is typically
-is less performant than C extensions.
\ No newline at end of file
diff --git a/changelog/2110.feature.rst b/changelog/2110.feature.rst
deleted file mode 100644
index 666cf4eb..00000000
--- a/changelog/2110.feature.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-Added ``ssl_minimum_version`` and ``ssl_maximum_version`` options which set
-``SSLContext.minimum_version`` and ``SSLContext.maximum_version``.
-
-Changed ``ssl_version`` to instead set the corresponding ``SSLContext.minimum_version``
-and ``SSLContext.maximum_version`` values.  Regardless of ``ssl_version`` passed
-``SSLContext`` objects are now constructed using ``ssl.PROTOCOL_TLS_CLIENT``.
-
-Deprecated ``ssl_version`` option in favor of ``ssl_minimum_version``. ``ssl_version``
-will be removed in a future 2.x release of urllib3.
diff --git a/changelog/2113.removal.rst b/changelog/2113.removal.rst
deleted file mode 100644
index 836c7e36..00000000
--- a/changelog/2113.removal.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-Removed fallback on certificate ``commonName`` in ``match_hostname()`` function.
-
-This behavior was deprecated in May 2000 in RFC 2818. Instead only ``subjectAltName``
-is used to verify the hostname by default. To enable verifying the hostname against
-``commonName`` use ``SSLContext.hostname_checks_common_name = True``.
\ No newline at end of file
diff --git a/changelog/2118.bugfix.rst b/changelog/2118.bugfix.rst
deleted file mode 100644
index 7f58d9a7..00000000
--- a/changelog/2118.bugfix.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Fixed ``socket.error.errno`` when raised from pyOpenSSL's ``OpenSSL.SSL.SysCallError``.
\ No newline at end of file
diff --git a/changelog/2120.feature.rst b/changelog/2120.feature.rst
deleted file mode 100644
index 7723eee4..00000000
--- a/changelog/2120.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Changed usage of the deprecated ``socket.error`` to ``OSError``.
\ No newline at end of file
diff --git a/changelog/2128.removal.rst b/changelog/2128.removal.rst
deleted file mode 100644
index abf412f9..00000000
--- a/changelog/2128.removal.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-Standardized :meth:`~urllib3.response.HTTPResponse.read` to respect the semantics of BufferedIOBase regardless of compression. Specifically, this method:
-
-* only returns an empty bytes object to indicate EOF (that is, the response has been fully consumed),
-* never returns more bytes than requested,
-* can issue any number of system calls: zero, one or multiple.
-
-If you want each :meth:`~urllib3.response.HTTPResponse.read` call to issue a single system call, you need to disable decompression by setting ``decode_content=False``.
diff --git a/changelog/2133.feature.rst b/changelog/2133.feature.rst
deleted file mode 100644
index be9754cc..00000000
--- a/changelog/2133.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Added ``HTTPSProxyError`` when the initial TLS handshake to the proxy fails.
\ No newline at end of file
diff --git a/changelog/2150.feature.rst b/changelog/2150.feature.rst
deleted file mode 100644
index 55617184..00000000
--- a/changelog/2150.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Added top-level ``urllib3.request`` function which uses a preconfigured module-global ``PoolManager`` instance.
\ No newline at end of file
diff --git a/changelog/2168.removal.rst b/changelog/2168.removal.rst
deleted file mode 100644
index 01c23db2..00000000
--- a/changelog/2168.removal.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-Removed support for OpenSSL versions earlier than 1.1.1 or that don't have SNI support.
-When an incompatible OpenSSL version is detected an ``ImportError`` is raised.
-
-Removed support for Python with an ``ssl`` module compiled with LibreSSL, CiscoSSL,
-wolfSSL, and all other OpenSSL alternatives. Python is moving to require OpenSSL with PEP 644.
-
-Changed ``urllib3.util.create_urllib3_context`` to not override the system cipher suites with
-a default value. The new default will be cipher suites configured by the operating system.
-
-Removed ``DEFAULT_CIPHERS``, ``HAS_SNI``, ``USE_DEFAULT_SSLCONTEXT_CIPHERS``, from the private module ``urllib3.util.ssl_``.
-
-Removed ``urllib3.exceptions.SNIMissingWarning``.
diff --git a/changelog/2197.feature.rst b/changelog/2197.feature.rst
deleted file mode 100644
index 006a6bd0..00000000
--- a/changelog/2197.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Added ``FullPoolError`` which is raised when ``PoolManager(block=True)`` and a connection is returned to a full pool.
\ No newline at end of file
diff --git a/changelog/2209.feature.rst b/changelog/2209.feature.rst
deleted file mode 100644
index 932d7fd5..00000000
--- a/changelog/2209.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Added support for Python 3.10.
\ No newline at end of file
diff --git a/changelog/2213.bugfix.rst b/changelog/2213.bugfix.rst
deleted file mode 100644
index f28810a2..00000000
--- a/changelog/2213.bugfix.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Fixed the default value of ``HTTPSConnection.socket_options`` to match ``HTTPConnection``.
\ No newline at end of file
diff --git a/changelog/2216.feature.rst b/changelog/2216.feature.rst
deleted file mode 100644
index 51395846..00000000
--- a/changelog/2216.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Added ``HTTPHeaderDict`` to the top-level ``urllib3`` namespace.
\ No newline at end of file
diff --git a/changelog/2233.removal.rst b/changelog/2233.removal.rst
deleted file mode 100644
index 6a66180c..00000000
--- a/changelog/2233.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-``urllib3.contrib.pyopenssl`` module no longer supports using SSLv3.0 even when support is available from the compiled OpenSSL library.
diff --git a/changelog/2242.feature.rst b/changelog/2242.feature.rst
deleted file mode 100644
index 8c95e205..00000000
--- a/changelog/2242.feature.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Added support for configuring header merging behavior with HTTPHeaderDict
-
-When using a ``HTTPHeaderDict`` to provide headers for a request, by default duplicate
-header values will be repeated. But if ``combine=True`` is passed into a call to
-``HTTPHeaderDict.add``, then the added header value will be merged in with an existing
-value into a comma-separated list (``X-My-Header: foo, bar``).
diff --git a/changelog/2243.feature.rst b/changelog/2243.feature.rst
deleted file mode 100644
index edd93e47..00000000
--- a/changelog/2243.feature.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-Added the ``json`` parameter to ``urllib3.request()``, ``PoolManager.request()``, and ``ConnectionPool.request()`` methods to send JSON bodies in requests. Using this parameter will set the header ``Content-Type: application/json`` if ``Content-Type`` isn't already defined.
-
-Added support for parsing JSON response bodies with ``HTTPResponse.json()`` method.
diff --git a/changelog/2257.removal.rst b/changelog/2257.removal.rst
deleted file mode 100644
index 01717639..00000000
--- a/changelog/2257.removal.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-Changed ``multipart/form-data`` header parameter formatting matches the WHATWG
-HTML Standard as of 2021-06-10. Control characters in filenames are no
-longer percent encoded.
-
-``format_header_param_html5`` and ``format_header_param`` are
-deprecated names for ``format_multipart_header_param``.
-
-The ``RequestField`` ``header_formatter`` parameter is deprecated in
-favor of overriding the ``_render_part`` method.
diff --git a/changelog/2267.removal.rst b/changelog/2267.removal.rst
deleted file mode 100644
index 5ee1f07e..00000000
--- a/changelog/2267.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Deprecated the ``strict`` parameter as it's not longer needed in Python 3.x.
\ No newline at end of file
diff --git a/changelog/2269.removal.rst b/changelog/2269.removal.rst
deleted file mode 100644
index 10451a36..00000000
--- a/changelog/2269.removal.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Removed the ``urllib3.request`` module. ``urllib3.request.RequestMethods`` has been made a private API.
-
-This change was made to ensure that ``from urllib3 import request`` imported the top-level ``request()``
-function instead of the ``urllib3.request`` module.
\ No newline at end of file
diff --git a/changelog/2271.removal.rst b/changelog/2271.removal.rst
deleted file mode 100644
index 9926efb6..00000000
--- a/changelog/2271.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Deprecated the ``NewConnectionError.pool`` attribute which will be removed in a future urllib3 v2.x release.
\ No newline at end of file
diff --git a/changelog/2272.bugfix.rst b/changelog/2272.bugfix.rst
deleted file mode 100644
index 1894a005..00000000
--- a/changelog/2272.bugfix.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Fixed a bug where ``headers`` would be modified by the ``remove_headers_on_redirect`` feature.
\ No newline at end of file
diff --git a/changelog/2277.bugfix.rst b/changelog/2277.bugfix.rst
deleted file mode 100644
index 4ac4a070..00000000
--- a/changelog/2277.bugfix.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Fixed a reference cycle bug in ``urllib3.util.connection.create_connection()``.
\ No newline at end of file
diff --git a/changelog/2305.feature.rst b/changelog/2305.feature.rst
deleted file mode 100644
index dd75db89..00000000
--- a/changelog/2305.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Added ``NameResolutionError`` exception when a DNS error occurs.
\ No newline at end of file
diff --git a/changelog/2336.removal.rst b/changelog/2336.removal.rst
deleted file mode 100644
index df316fc4..00000000
--- a/changelog/2336.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Removed support for Python 3.6.
\ No newline at end of file
diff --git a/changelog/2339.removal.rst b/changelog/2339.removal.rst
deleted file mode 100644
index 36730bd5..00000000
--- a/changelog/2339.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Removed the deprecated ``urllib3.contrib.ntlmpool`` module.
\ No newline at end of file
diff --git a/changelog/2373.feature.rst b/changelog/2373.feature.rst
deleted file mode 100644
index b20e3a0e..00000000
--- a/changelog/2373.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Changed default ``SSLContext.minimum_version`` to be ``TLSVersion.TLSv1_2`` in line with Python 3.10.
\ No newline at end of file
diff --git a/changelog/2409.feature.rst b/changelog/2409.feature.rst
deleted file mode 100644
index a9e4bdb0..00000000
--- a/changelog/2409.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Added ``proxy_assert_hostname`` and ``proxy_assert_fingerprint`` kwargs to ``ProxyManager``.
diff --git a/changelog/2494.feature.rst b/changelog/2494.feature.rst
deleted file mode 100644
index 1a774c50..00000000
--- a/changelog/2494.feature.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-Replaced ``Retry.BACK0FF_MAX`` with ``Retry.DEFAULT_BACKOFF_MAX``.
-
-Added a configurable ``backoff_max`` parameter to the ``Retry`` class.
-If a custom ``backoff_max`` is provided to the ``Retry`` class, it
-will replace the ``Retry.DEFAULT_BACKOFF_MAX``.
diff --git a/changelog/2513.bugfix.rst b/changelog/2513.bugfix.rst
deleted file mode 100644
index 9354e387..00000000
--- a/changelog/2513.bugfix.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Fixed reading 2 or more GiB of data at a time using ``urllib3.response.HTTPResponse.read``.
\ No newline at end of file
diff --git a/changelog/2514.bugfix.rst b/changelog/2514.bugfix.rst
deleted file mode 100644
index ff09c380..00000000
--- a/changelog/2514.bugfix.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Change `enforce_content_length` default to True, preventing silent data loss when reading streamed responses.
diff --git a/changelog/2515.feature.rst b/changelog/2515.feature.rst
deleted file mode 100644
index 5d07702e..00000000
--- a/changelog/2515.feature.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Changed ``HTTPConnection.request()`` to always use lowercase chunk boundaries when sending requests with ``Transfer-Encoding: chunked``.
diff --git a/changelog/2520.feature.rst b/changelog/2520.feature.rst
deleted file mode 100644
index 9bc6757e..00000000
--- a/changelog/2520.feature.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-Added the ``authority`` property to the Url class as per RFC 3986 3.2.
-This property should be used in place of ``netloc`` for users who
-want to include the userinfo (auth) component of the URI.
diff --git a/changelog/2589.feature.rst b/changelog/2589.feature.rst
deleted file mode 100644
index b8f1d000..00000000
--- a/changelog/2589.feature.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-Changed the error raised when connecting via HTTPS when the ``ssl`` module isn't
-available from ``SSLError`` to ``ImportError``.
\ No newline at end of file
diff --git a/changelog/2628.bugfix.rst b/changelog/2628.bugfix.rst
deleted file mode 100644
index a02ad10a..00000000
--- a/changelog/2628.bugfix.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Wrap OpenSSL.SSL.Error with ssl.SSLError in PyOpenSSLContext.load_cert_chain.
diff --git a/changelog/2645.bugfix.rst b/changelog/2645.bugfix.rst
deleted file mode 100644
index 564a1e5c..00000000
--- a/changelog/2645.bugfix.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-Fixed an issue where an ``HTTPConnection`` instance would erroneously reuse the socket
-read timeout value from reading the previous response instead of a newly configured connect timeout.
-Instead now if ``HTTPConnection.timeout`` is updated before sending the next request the new timeout value will be used.
diff --git a/changelog/2648.feature.rst b/changelog/2648.feature.rst
deleted file mode 100644
index 5ea256a8..00000000
--- a/changelog/2648.feature.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-Modified ``urllib3.HTTPConnection.getresponse`` to return an instance of ``urllib3.HTTPResponse`` instead of ``http.client.HTTPResponse``.
-
-Removed ``urllib3.HTTPResponse.from_httplib``.
diff --git a/changelog/2691.removal.rst b/changelog/2691.removal.rst
deleted file mode 100644
index 73c83dbf..00000000
--- a/changelog/2691.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Deprecated ``urllib3.contrib.pyopenssl`` module which will be removed in future urllib3 v2.x release.
\ No newline at end of file
diff --git a/changelog/2692.removal.rst b/changelog/2692.removal.rst
deleted file mode 100644
index 1e4e7663..00000000
--- a/changelog/2692.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Deprecated ``urllib3.contrib.securetransport`` module which will be removed in future urllib3 v2.x release.
\ No newline at end of file
diff --git a/changelog/883.removal.rst b/changelog/883.removal.rst
deleted file mode 100644
index d78c07be..00000000
--- a/changelog/883.removal.rst
+++ /dev/null
@@ -1,1 +0,0 @@
-Removed support for Python 2.7 and 3.5.
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index c2f81d37..1407431a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,7 +7,7 @@ urllib3
 
    For Enterprise <https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs>
    Community Discord <https://discord.gg/urllib3>
-   v2-roadmap
+   v2-migration-guide
    sponsors
    user-guide
    advanced-usage
diff --git a/docs/v2-migration-guide.rst b/docs/v2-migration-guide.rst
new file mode 100644
index 00000000..6dac8c95
--- /dev/null
+++ b/docs/v2-migration-guide.rst
@@ -0,0 +1,313 @@
+v2.0 Migration Guide
+====================
+
+**urllib3 v2.0 is now available!** Read below for how to get started and what is contained in the new major release.
+
+**🚀 Migrating from 1.x to 2.0**
+--------------------------------
+
+We're maintaining **functional API compatibility for most users** to make the
+migration an easy choice for almost everyone. Most changes are either to default
+configurations, supported Python versions, or internal implementation details.
+So unless you're in a specific situation you should notice no changes! 🎉
+
+.. note::
+
+  If you have difficulty migrating to v2.0 or following this guide
+  you can `open an issue on GitHub <https://github.com/urllib3/urllib3/issues>`_
+  or reach out in `our community Discord channel <https://discord.gg/urllib3>`_.
+
+
+Timeline for deprecations and breaking changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The 2.x initial release schedule will look like this:
+
+* urllib3 ``v2.0.0-alpha1`` will be released in November 2022. This release
+  contains **minor breaking changes and deprecation warnings for other breaking changes**.
+  There may be other pre-releases to address fixes before v2.0.0 is released.
+* urllib3 ``v2.0.0`` will be released in early 2023 after some initial integration testing
+  against dependent packages and fixing of bug reports.
+* urllib3 ``v2.1.0`` will be released in the summer of 2023 with **all breaking changes
+  being warned about in v2.0.0**.
+
+.. warning::
+
+  Please take the ``DeprecationWarnings`` you receive when migrating from v1.x to v2.0 seriously
+  as they will become errors after 2.1.0 is released.
+
+
+What are the important changes?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here's a short summary of which changes in urllib3 v2.0 are most important:
+
+- Python version must be **3.7 or later** (previously supported Python 2.7, 3.5, and 3.6).
+- Removed support for non-OpenSSL TLS libraries (like LibreSSL and wolfSSL).
+- Removed support for OpenSSL versions older than 1.1.1.
+- Removed support for Python implementations that aren't CPython or PyPy3 (previously supported Google App Engine, Jython).
+- Removed the ``urllib3.contrib.ntlmpool`` module.
+- Deprecated the ``urllib3.contrib.pyopenssl``, ``urllib3.contrib.securetransport`` modules, will be removed in v2.1.0.
+- Deprecated the ``urllib3[secure]`` extra, will be removed in v2.1.0.
+- Changed the default minimum TLS version to TLS 1.2 (previously was TLS 1.0).
+- Removed support for verifying certificate hostnames via ``commonName``, now only ``subjectAltName`` is used.
+- Removed the default set of TLS ciphers, instead now urllib3 uses the list of ciphers configured by the system.
+
+For a full list of changes you can look at `the changelog <https://github.com/urllib3/urllib3/blob/main/CHANGES.rst>`_.
+
+
+Migrating as a package maintainer?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're a maintainer of a package that uses urllib3 under the hood then this section is for you.
+You may have already seen an issue opened from someone on our team about the upcoming release.
+
+The primary goal for migrating to urllib3 v2.x should be to ensure your package supports **both urllib3 v1.26.x and v2.0 for some time**.
+This is to reduce the chance that diamond dependencies are introduced into your users' dependencies which will then cause issues
+with them upgrading to the latest version of **your package**.
+
+The first step to supporting urllib3 v2.0 is to make sure the version v2.x not being excluded by ``install_requires``. You should
+ensure your package allows for both urllib3 1.26.x and 2.0 to be used:
+
+.. code-block:: python
+
+  # setup.py (setuptools)
+  setup(
+    ...
+    install_requires=["urllib3>=1.26,<3"]
+  )
+
+  # pyproject.toml (hatch)
+  [project]
+  dependencies = [
+    "urllib3>=1.26,<3"
+  ]
+
+Next you should try installing urllib3 v2.0 locally and run your test suite.
+
+.. code-block:: bash
+
+  $ python -m pip install -U --pre 'urllib3>2'
+
+
+Because there are many ``DeprecationWarnings`` you should ensure that you're
+able to see those warnings when running your test suite. To do so you can add
+the following to your test setup to ensure even ``DeprecationWarnings`` are
+output to the terminal:
+
+.. code-block:: bash
+
+  # Set PYTHONWARNING=default to show all warnings.
+  $ export PYTHONWARNINGS="default"
+
+  # Run your test suite and look for failures.
+  # Pytest automatically prints all warnings.
+  $ pytest tests/
+
+or you can opt-in within your Python code:
+
+.. code-block:: python
+
+  # You can change warning filters according to the filter rules:
+  # https://docs.python.org/3/library/warnings.html#warning-filter
+  import warnings
+  warnings.filterwarnings("default", category=DeprecationWarning)
+
+Any failures or deprecation warnings you receive should be fixed as urllib3 v2.1.0 will remove all
+deprecated features. Many deprecation warnings will make suggestions about what to do to avoid the deprecated feature.
+
+Warnings will look something like this:
+
+.. code-block:: bash
+
+  DeprecationWarning: 'ssl_version' option is deprecated and will be removed
+  in urllib3 v2.1.0. Instead use 'ssl_minimum_version'
+
+Continue removing deprecation warnings until there are no more. After this you can publish a new release of your package
+that supports both urllib3 v1.26.x and v2.x.
+
+.. note::
+
+  If you're not able to support both 1.26.x and v2.0 of urllib3 at the same time with your package please
+  `open an issue on GitHub <https://github.com/urllib3/urllib3/issues>`_ or reach out in
+  `our community Discord channel <https://discord.gg/urllib3>`_.
+
+
+Migrating as an application developer?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're someone who writes Python but doesn't ship as a package (things like web services, data science, tools, and more) this section is for you.
+
+Python environments only allow for one version of a dependency to be installed per environment which means
+that **all of your dependencies using urllib3 need to support v2.0 for you to upgrade**.
+
+The best way to visualize relationships between your dependencies is using `pipdeptree <https://pypi.org/project/pipdeptree>`_ and ``$ pipdeptree --reverse``:
+
+.. code-block:: bash
+
+  # From inside your Python environment:
+  $ python -m pip install pipdeptree
+  # We only care about packages requiring urllib3
+  $ pipdeptree --reverse | grep "requires: urllib3"
+
+  - botocore==1.29.8 [requires: urllib3>=1.25.4,<1.27]
+  - requests==2.28.1 [requires: urllib3>=1.21.1,<1.27]
+
+Reading the output from above, there are two packages which depend on urllib3: ``botocore`` and ``requests``.
+The versions of these two packages both require urllib3 that is less than v2.0 (ie ``<1.27``).
+
+Because both of these packages require urllib3 before v2.0 the new version of urllib3 can't be installed
+by default. There are ways to force installing the newer version of urllib3 v2.0 (ie pinning to ``urllib3==2.0.0``)
+which you can do to test your application.
+
+It's important to know that even if you don't upgrade all of your services to 2.x
+immediately you will `receive security fixes on the 1.26.x release stream <#security-fixes-for-urllib3-v1-26-x>` for some time.
+
+
+Security fixes for urllib3 v1.26.x
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Thanks to support from `Tidelift <https://tidelift.com/subscription/pkg/pypi-urllib3>`_
+we're able to continue supporting the v1.26.x release stream with
+security fixes for the foreseeable future 💖
+
+However, upgrading is still recommended as **no new feature developments or non-critical
+bug fixes will be shipped to the 1.26.x release stream**.
+
+If your organization relies on urllib3 and is interested in continuing support you can learn
+more about the `Tidelift Subscription for Enterprise <https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs>`_.
+
+
+**💪 User-friendly features**
+-----------------------------
+
+urllib3 has always billed itself as a **user-friendly HTTP client library**.
+In the spirit of being even more user-friendly we've added two features
+which should make using urllib3 for tinkering sessions, throw-away scripts,
+and smaller projects a breeze!
+
+urllib3.request()
+~~~~~~~~~~~~~~~~~
+
+Previously the highest-level API available for urllib3 was a ``PoolManager``,
+but for many cases configuring a poolmanager is extra steps for no benefit.
+To make using urllib3 as simple as possible we've added a top-level function
+for sending requests from a global poolmanager instance:
+
+.. code-block:: python
+
+  >>> import urllib3
+  >>> resp = urllib3.request("GET", "https://example.com")
+  >>> resp.status
+  200
+
+JSON support for requests and responses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+JSON is everywhere – and now it's in urllib3, too!
+
+If you'd like to send JSON in a request body or deserialize a response body
+from JSON into Python objects you can now use the new ``json=`` parameter
+for requests and ``HTTPResponse.json()`` method on responses:
+
+.. code-block:: python
+
+  import urllib3
+
+  # Send a request with a JSON body.
+  # This adds 'Content-Type: application/json' by default.
+  resp = urllib3.request(
+      "POST", "https://example.api.com",
+      json={"key": "value"}
+  )
+
+  # Receive a JSON body in the response.
+  resp = urllib3.request("GET", "https://xkcd.com/2347/info.0.json")
+
+  # There's always an XKCD...
+  resp.json()
+  {
+    "num": 2347,
+    "img": "https://imgs.xkcd.com/comics/dependency.png",
+    "title": "Dependency",
+    ...
+  }
+
+
+**✨ Optimized for Python 3.7+**
+--------------------------------
+
+In v2.0 we'll be specifically targeting
+CPython 3.7+ and PyPy 7.0+ (compatible with CPython 3.7)
+and dropping support for Python versions 2.7, 3.5, and 3.6.
+
+By dropping end-of-life Python versions we're able to optimize
+the codebase for Python 3.7+ by using new features to improve
+performance and reduce the amount of code that needs to be executed
+in order to support legacy versions.
+
+
+**📜 Type-hinted APIs**
+-----------------------
+
+You're finally able to run Mypy or other type-checkers
+on code using urllib3. This also means that for IDEs
+that support type hints you'll receive better suggestions
+from auto-complete. No more confusion with ``**kwargs``!
+
+We've also added API interfaces like ``BaseHTTPResponse``
+and ``BaseHTTPConnection`` to ensure that when you're sub-classing
+an interface you're only using supported public APIs to ensure
+compatibility and minimize breakages down the road.
+
+.. note::
+
+  If you're one of the rare few who is subclassing connections
+  or responses you should take a closer look at detailed changes
+  in `the changelog <https://github.com/urllib3/urllib3/blob/main/CHANGES.rst>`_.
+
+
+**🔐 Modern security by default**
+---------------------------------
+
+HTTPS requires TLS 1.2+
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Greater than 95% of websites support TLS 1.2 or above.
+At this point we're comfortable switching the default
+minimum TLS version to be 1.2 to ensure high security
+for users without breaking services.
+
+Dropping TLS 1.0 and 1.1 by default means you
+won't be vulnerable to TLS downgrade attacks
+if a vulnerability in TLS 1.0 or 1.1 were discovered in
+the future. Extra security for free! By dropping TLS 1.0
+and TLS 1.1 we also tighten the list of ciphers we need
+to support to ensure high security for data traveling
+over the wire.
+
+If you still need to use TLS 1.0 or 1.1 in your application
+you can still upgrade to v2.0, you'll only need to set
+``ssl_minimum_version`` to the proper value to continue using
+legacy TLS versions.
+
+
+Stop verifying commonName in certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Dropping support the long deprecated ``commonName``
+field on certificates in favor of only verifying
+``subjectAltName`` to put us in line with browsers and
+other HTTP client libraries and to improve security for our users.
+
+
+Certificate verification via SSLContext
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default certificate verification is handled by urllib3
+to support legacy Python versions, but now we can
+rely on Python's certificate verification instead! This
+should result in a speedup for verifying certificates
+and means that any improvements made to certificate
+verification in Python or OpenSSL will be immediately
+available.
diff --git a/docs/v2-roadmap.rst b/docs/v2-roadmap.rst
deleted file mode 100644
index 3aa428ab..00000000
--- a/docs/v2-roadmap.rst
+++ /dev/null
@@ -1,177 +0,0 @@
-v2.0 Roadmap
-============
-
-.. important::
-
-   We're seeking `sponsors and supporters for urllib3 v2.0 on Open Collective <https://github.com/sponsors/urllib3>`_.
-   There's a lot of work to be done for our small team and we want to make sure
-   development can get completed on-time while also fairly compensating contributors
-   for the additional effort required for a large release like ``v2.0``.
-
-   Additional information available within the :doc:`sponsors` section of our documentation.
-
-
-**🚀 Functional API Compatibility**
------------------------------------
-
-We're maintaining **99% functional API compatibility** to make the
-migration an easy choice for most users. Migration from v1.x to v2.x
-should be the simplest major version upgrade you've ever completed.
-
-Most changes are either to default configurations, supported Python versions,
-and internal implementation details. So unless you're in a specific situation
-you should notice no changes! 🎉
-
-
-v1.26.x Security and Bug Fixes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Thanks to support from `Tidelift <https://tidelift.com/subscription/pkg/pypi-urllib3>`_
-we're able to continue supporting v1.26.x releases with
-both security and bug fixes for the foreseeable future 💖
-
-If your organization relies on urllib3 and is interested in continuing support you can learn
-more about the `Tidelift Subscription for Enterprise <https://tidelift.com/subscription/pkg/pypi-urllib3?utm_source=pypi-urllib3&utm_medium=referral&utm_campaign=docs>`_.
-
-
-**🔐 Modern Security by Default**
----------------------------------
-
-HTTPS requires TLS 1.2+
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Greater than 95% of websites support TLS 1.2 or above.
-At this point we're comfortable switching the default
-minimum TLS version to be 1.2 to ensure high security
-for users without breaking services.
-
-Dropping TLS 1.0 and 1.1 by default means you
-won't be vulnerable to TLS downgrade attacks
-if a vulnerability in TLS 1.0 or 1.1 were discovered in
-the future. Extra security for free! By dropping TLS 1.0
-and TLS 1.1 we also tighten the list of ciphers we need
-to support to ensure high security for data traveling
-over the wire.
-
-If you still need to use TLS 1.0 or 1.1 in your application
-you can still upgrade to v2.0, you'll only need to set
-``ssl_minimum_version`` to the proper value to continue using
-legacy TLS versions.
-
-
-Stop Verifying CommonName in Certificates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Dropping support the long deprecated ``commonName``
-field on certificates in favor of only verifying
-``subjectAltName`` to put us in line with browsers and
-other HTTP client libraries and to improve security for our users.
-
-
-Certificate Verification via SSLContext
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default certificate verification is handled by urllib3
-to support legacy Python versions, but now we can
-rely on Python's certificate verification instead! This
-should result in a speedup for verifying certificates
-and means that any improvements made to certificate
-verification in Python or OpenSSL will be immediately
-available.
-
-
-**✨ Optimized for Python 3.7+**
---------------------------------
-
-In v2.0 we'll be specifically targeting
-CPython 3.7+ and PyPy 7.0+ (compatible with CPython 3.7)
-and dropping support for Python versions 2.7, 3.5, and 3.6.
-
-By dropping end-of-life Python versions we're able to optimize
-the codebase for Python 3.7+ by using new features to improve
-performance and reduce the amount of code that needs to be executed
-in order to support legacy versions.
-
-
-**🔮 Tracing**
---------------
-
-Currently with urllib3 it's tough to get low-level insights into what
-how your HTTP client is performing and what your connection information
-looks like. In v2.0 we'll be adding tracing and telemetry information
-to HTTP response objects including:
-
-- Connection ID
-- IP Address resolved by DNS
-- Request Method, Target, and Headers
-- TLS Version and Cipher
-- Certificate Fingerprint, subjectAltName, and Validity Information
-- Timings for DNS, Request Data, First Byte in Response
-
-
-**📜 Type-Hinted APIs**
------------------------
-
-You'll finally be able to run Mypy or other type-checkers
-on code using urllib3. This also means that for IDEs
-that support type hints you'll receive better suggestions
-from auto-complete. No more confusing with ``**kwargs``!
-
-We'll also add API interfaces to ensure that when
-you're sub-classing an interface you're only using
-supported public APIs to ensure compatibility and
-minimize breakages down the road.
-
-
-**🎁 ...and many more features!**
----------------------------------
-
-- Top-level ``urllib3.request()`` API
-- Streaming ``multipart/form-encoded`` Request Data
-- More Powerful and Configurable Retry Logic
-
-If there's a feature you don't see here but would like to see
-in urllib3 v2.0, there's an open GitHub issue for making
-feature suggestions.
-
-
-**📅 Release and Migration Schedule**
--------------------------------------
-
-We're aiming for all ``v2.x`` features to be released in **mid-to-late 2021**.
-
-Here's what the release and migration schedule will look like leading up
-to v2.0 being released:
-
-- Development of ``v2.x`` breaking changes starts.
-- Release ``v1.26.0`` with deprecation warnings for ``v2.0.0`` breaking changes.
-  This will be the last non-patch release within the ``v1.x`` stream.
-- Release ``v2.0.0-alpha1`` once all breaking changes have been completed.
-  We'll wait for users to report issues, bugs, and unexpected
-  breakages at this stage to ensure the release ``v2.0.0`` goes smoothly.
-- Development of remaining ``v2.x`` features starts.
-- Release ``v2.0.0`` which will be identical to ``v2.0.0-alpha1``.
-- Release ``v2.1.0`` with remaining ``v2.x`` features.
-
-Deprecation warnings within ``v1.26.x`` will be opt-in by default.
-
-**More detailed Application Migration Guide coming soon.**
-
-For Package Maintainers
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Since this is the first major release in almost 9 years some users may
-be caught off-guard by a new major release of urllib3. We're mitigating this by
-trying to make ``v2.x`` API-compatible with ``v1.x``.
-
-If your application or library uses urllib3 and you'd like to be extra
-cautious about not breaking your users, you can pin urllib3 like so
-until you ensure compatibility with ``v2.x``:
-
-.. code-block:: python
-
-   # 'install_requires' or 'requirements.txt'
-   "urllib3>=1.25,<2"
-
-We'd really appreciate testing compatibility
-and providing feedback on ``v2.0.0-alpha1`` once released.
diff --git a/src/urllib3/_version.py b/src/urllib3/_version.py
index e0157066..2662fa43 100644
--- a/src/urllib3/_version.py
+++ b/src/urllib3/_version.py
@@ -1,2 +1,2 @@
 # This file is protected via CODEOWNERS
-__version__ = "2.0.0.dev0"
+__version__ = "2.0.0a1"
diff --git a/src/urllib3/poolmanager.py b/src/urllib3/poolmanager.py
index 62c8ee71..b7b4f69b 100644
--- a/src/urllib3/poolmanager.py
+++ b/src/urllib3/poolmanager.py
@@ -324,7 +324,7 @@ class PoolManager(RequestMethods):
         if "strict" in request_context:
             warnings.warn(
                 "The 'strict' parameter is no longer needed on Python 3+. "
-                "This will raise an error in urllib3 v3.0.0.",
+                "This will raise an error in urllib3 v2.1.0.",
                 DeprecationWarning,
             )
             request_context.pop("strict")


Test patch:
diff --git a/test/test_poolmanager.py b/test/test_poolmanager.py
index 0a75063b..847a54a8 100644
--- a/test/test_poolmanager.py
+++ b/test/test_poolmanager.py
@@ -274,7 +274,7 @@ class TestPoolManager:
 
         msg = (
             "The 'strict' parameter is no longer needed on Python 3+. "
-            "This will raise an error in urllib3 v3.0.0."
+            "This will raise an error in urllib3 v2.1.0."
         )
         record = records[0]
         assert isinstance(record.message, Warning)