Skip to content

Commit f6a3c78

Browse files
mergify[bot]majorgreys
mergify[bot]
and
majorgreys
authored
docs: release notes for 1.0 revisions (#3554) (#3570)
* docs: release notes for 1.0 revisions * docs: release notes for 1.0 revisions (cherry picked from commit 3e58888) Co-authored-by: Tahir H. Butt <[email protected]>
1 parent 3c27c55 commit f6a3c78

10 files changed

+354
-149
lines changed

‎docs/advanced_usage.rst‎

Lines changed: 0 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -296,51 +296,6 @@ propagate a `rpc_metadata` dictionary over the wire::
296296
span.set_tag('my_rpc_method', method)
297297

298298

299-
.. _`Upgrading and deprecation warnings`:
300-
301-
Upgrading and deprecation warnings
302-
----------------------------------
303-
304-
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.
305-
306-
.. _upgrade-0.x:
307-
308-
Upgrading from 0.x to 1.x
309-
^^^^^^^^^^^^^^^^^^^^^^^^^
310-
311-
As of v0.60.0, you can use warning filters for ``ddtrace.DDTraceDeprecationWarning`` to find and replace usages of deprecated features.
312-
313-
For those using ``pytest``::
314-
315-
pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py
316-
317-
318-
Otherwise, you can set the environment variable ``DD_TRACE_RAISE_DEPRECATIONWARNING`` to configure the warning filter::
319-
320-
DD_TRACE_RAISE_DEPRECATIONWARNING=1 python app.py
321-
322-
323-
Though ``ddtrace.DDTraceDeprecationWarning`` is not available before v0.60.0, you can still enable all deprecation warnings and filter the application or tests logs for deprecations specific to the ``ddtrace`` library::
324-
325-
$ python -Wall app.py
326-
327-
# or
328-
329-
$ PYTHONWARNINGS=all python app.py
330-
331-
332-
In addition to deprecation warnings, you can search a code base using the following patterns to identify the deprecated environment variables::
333-
334-
git grep -e "DATADOG_[A-Z_]*" \
335-
-e "DATADOG_SERVICE_NAME" \
336-
-e "DD_CALL_BASIC_CONFIG" \
337-
-e "DD_LOGGING_RATE_LIMIT" \
338-
-e "DD_SERVICE_NAME" \
339-
-e "DD_TRACER_PARTIAL_FLUSH_ENABLED" \
340-
-e "DD_TRACER_PARTIAL_FLUSH_MIN_SPANS"
341-
342-
343-
344299
Trace Filtering
345300
---------------
346301

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,5 +194,6 @@ Indices and tables
194194
contributing
195195
troubleshooting
196196
versioning
197+
upgrading
197198
api
198199
release_notes

‎docs/release_notes.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ Release Notes
3333
- "profiling-fix-memory-alloc-numbers-a280c751c8f250ba.yaml"
3434
- "pymongo-4.0.2-1f5d2b6af5c158d2.yaml"
3535
- "disable-internal-tag-propagation-dff3e799fb056584.yaml"
36+
- "add-span-get-tags-metrics-7969ba7843dcc24d.yaml"
3637

3738

3839
Prior Releases

‎docs/upgrading.rst‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
Upgrading
2+
---------
3+
4+
.. _upgrade-0.x:
5+
6+
Upgrade 0.x
7+
^^^^^^^^^^^
8+
9+
.. _`Upgrading and deprecation warnings`:
10+
11+
Deprecation warnings
12+
********************
13+
14+
As of v0.60.0, the library provides `Python
15+
warnings <https://docs.python.org/3/library/warnings.html>`_ for deprecations
16+
with an additional warning category ``ddtrace.DDTraceDeprecationWarning``.
17+
18+
This warning category can be used in configuring pytest `warnings capture <https://docs.pytest.org/en/6.2.x/warnings.html>`_ to turn warnings into errors::
19+
20+
pytest -W "error::ddtrace.DDTraceDeprecationWarning" tests.py
21+
22+
23+
In addition, the environment variable ``DD_TRACE_RAISE_DEPRECATIONWARNING`` is provided to configure the warning filter to raise an exception in an application instrumented with ddtrace::
24+
25+
DD_TRACE_RAISE_DEPRECATIONWARNING=1 ddtrace-run python app.py
26+
27+
28+
Before v0.60.0, you must enable all deprecation warnings and filter the application or tests logs for deprecations specific to the ddtrace library::
29+
30+
$ python -Wall app.py
31+
32+
# or
33+
34+
$ PYTHONWARNINGS=all python app.py
35+
36+
37+
Environment variables
38+
*********************
39+
40+
Use the following patterns to identify the deprecated environment variables in a code base::
41+
42+
git grep -e "DATADOG_[A-Z_]*" \
43+
-e "DATADOG_SERVICE_NAME" \
44+
-e "DD_CALL_BASIC_CONFIG" \
45+
-e "DD_LOGGING_RATE_LIMIT" \
46+
-e "DD_SERVICE_NAME" \
47+
-e "DD_TRACER_PARTIAL_FLUSH_ENABLED" \
48+
-e "DD_TRACER_PARTIAL_FLUSH_MIN_SPANS"

‎docs/versioning.rst‎

Lines changed: 32 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -15,16 +15,41 @@ Release support
1515
* - Release
1616
- :ref:`Support level<versioning_support_levels>`
1717
- Minimum Datadog Agent
18-
* - 0.x
18+
* - ``<1``
1919
- :ref:`Maintenance<versioning_support_maintenace>`
2020
-
21-
* - 1.x
21+
* - ``>=1.0,<2``
2222
- :ref:`General Availability<versioning_support_ga>`
2323
- 7.28
2424

2525

26-
Versions
27-
========
26+
.. _versioning_support_levels:
27+
28+
Support levels
29+
==============
30+
31+
32+
.. list-table::
33+
:header-rows: 1
34+
35+
* - Level
36+
- Policy
37+
38+
.. _versioning_support_ga:
39+
* - General Availability (GA)
40+
- Support for new features, bug and security fixes.
41+
42+
.. _versioning_support_maintenace:
43+
* - Maintenance
44+
- Does not receive new features. Support for critical bug fixes and security fixes only.
45+
* - End-of-life
46+
- No support.
47+
48+
49+
.. _versioning_release:
50+
51+
Release versions
52+
================
2853

2954

3055
The non-negative integer components of the **version format** (``v<MAJOR>.<MINOR>.<PATCH>``) are incremented by the criteria:
@@ -84,37 +109,14 @@ Supported runtimes
84109
- x86-64, i686, AArch64
85110
- CPython
86111
- 2.7, 3.5-3.10
87-
- 1.x
112+
- ``<2``
88113
* - MacOS
89114
- Intel, Apple Silicon
90115
- CPython
91116
- 2.7, 3.5-3.10
92-
- 1.x
117+
- ``<2``
93118
* - Windows
94119
- 64bit, 32bit
95120
- CPython
96121
- 2.7, 3.5-3.10
97-
- 1.x
98-
99-
100-
.. _versioning_support_levels:
101-
102-
Support levels
103-
==============
104-
105-
106-
.. list-table::
107-
:header-rows: 1
108-
109-
* - Level
110-
- Policy
111-
112-
.. _versioning_support_ga:
113-
* - General Availability (GA)
114-
- Full implementation of all features. Full support for new features, bug & security fixes.
115-
116-
.. _versioning_support_maintenace:
117-
* - Maintenance
118-
- Full implementation of existing features. Does not receive new features. Support for bug & security fixes only.
119-
* - End-of-life
120-
- No support.
122+
- ``<2``

‎releasenotes/notes/add-warning-after-shutdown-tracer-dd8799467c4d29c8.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
---
22
upgrade:
33
- |
4-
Spans started after the tracer has been shut down will no longer be sent to the Datadog Agent.
4+
Spans started after ``Tracer.shutdown()`` has been called will no longer be sent to the Datadog Agent.

‎releasenotes/notes/ddtrace-1.0-disable-basic-config-call-by-default-b677844e4a13a794.yaml‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,14 @@
11
---
22
upgrade:
3-
- ".. _disable-basic-config-call-by-default:
3+
- |
4+
.. _disable-basic-config-call-by-default:
45
56
67
Default value of ``DD_CALL_BASIC_CONFIG`` was updated from ``True`` to ``False``.
78
Call ``logging.basicConfig()`` to configure logging in your application.
8-
9-
"
109
deprecations:
11-
- ".. _deprecate-basic-config-call:
10+
- |
11+
.. _deprecate-basic-config-call:
1212
1313
1414
``DD_CALL_BASIC_CONFIG`` is deprecated.
15-
16-
"

0 commit comments

Comments
 (0)