docs: fix deprecation guide in release notes (#3347) (#3353)

(cherry picked from commit 48ed395)

Co-authored-by: Tahir H. Butt <[email protected]>

Author: mergify[bot]

docs/advanced_usage.rst

@@ -296,15 +296,29 @@ propagate a `rpc_metadata` dictionary over the wire::
             span.set_tag('my_rpc_method', method)
 
 
-Resolving deprecation warnings
-------------------------------
-Before upgrading, it’s a good idea to resolve any deprecation warnings raised by your project.
-These warnings must be fixed before upgrading, otherwise the ``ddtrace`` library
-will not work as expected. Our deprecation messages include the version where
-the behavior is altered or removed.
-
-In Python, deprecation warnings are silenced by default. To enable them you may
-add the following flag or environment variable::
+Upgrading and deprecation warnings
+----------------------------------
+
+Before upgrading, we recommend resolving any deprecation warnings raised in your application. The messages for the deprecation warnings include the version when the API will be changed or removed.
+
+.. _upgrade-0.x:
+
+0.x Release Line
+^^^^^^^^^^^^^^^^
+
+As of v0.59.0, you can enable warning filters for ddtrace library deprecations.
+
+For those using ``pytest``, add a filter for the ``ddtrace.DDTraceDeprecationWarning`` warning category::
+
+    pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py
+
+
+Otherwise, you must set the environment variable ``DD_TRACE_RAISE_DEPRECATIONWARNING`` which will configure the warning filter::
+
+    DD_TRACE_RAISE_DEPRECATIONWARNING=1 python app.py
+
+
+Before v0.59.0, you can still enable all deprecation warnings and filter the application or tests logs for deprecations specific the ``ddtrace`` library::
 
     $ python -Wall app.py
 

releasenotes/notes/release-1.0-758fc917e40d7eb3.yaml

@@ -18,12 +18,7 @@ prelude: >
 
 
   .. note::
-  Before upgrading to v1.0.0, we recommend installing ``ddtrace>=0.59.0,<1.0.0`` and running tests with `warning filters <https://docs.python.org/3.8/library/warnings.html#warning-filter>`_ set to raise ``ddtrace.warnings.DDTraceV1DeprecationWarning`` as errors or set the environment variable ``DD_TRACE_RAISE_DEPRECATIONWARNING``. For example::
-
-    $ DD_TRACE_RAISE_DEPRECATIONWARNING=1 python tests.py
-    $ pytest -W "error::ddtrace.warnings.DDTraceDeprecationWarning" tests.py
-    
-  Once all deprecation warnings are addressed you can safely upgrade to v1.0.0.
+    Before upgrading to v1.0.0, we recommend users enable deprecation warnings after having installed ``ddtrace>=0.59.0,<1.0.0``. See the upgrading and deprecation warnings section on the the :ref:`0.x Release Line <upgrade-0.x>` for further details.
 
 
   .. csv-table:: Upgrade from 0.x