From 40466a57ff3776bed6fd821c652b23e7e0546d7f Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Sat, 2 May 2020 09:55:34 -0300
Subject: [PATCH] Improve docs about junit_family warning message

From discussion in #6178
---
 doc/en/deprecations.rst   | 27 ++++++++++++++++++++-------
 src/_pytest/deprecated.py |  6 +++---
 2 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/doc/en/deprecations.rst b/doc/en/deprecations.rst
index 4d8177a543d..def84ee0fd0 100644
--- a/doc/en/deprecations.rst
+++ b/doc/en/deprecations.rst
@@ -80,22 +80,35 @@ Note that ``from_parent`` should only be called with keyword arguments for the p
 
 .. deprecated:: 5.2
 
-The default value of ``junit_family`` option will change to ``xunit2`` in pytest 6.0, given
-that this is the version supported by default in modern tools that manipulate this type of file.
+The default value of ``junit_family`` option will change to ``xunit2`` in pytest 6.0, which
+is an update of the old ``xunit1`` format and is supported by default in modern tools
+that manipulate this type of file (for example, Jenkins, Azure Pipelines, etc.).
 
-In order to smooth the transition, pytest will issue a warning in case the ``--junitxml`` option
-is given in the command line but ``junit_family`` is not explicitly configured in ``pytest.ini``::
+Users are recommended to try the new ``xunit2`` format and see if their tooling that consumes the JUnit
+XML file supports it.
 
-    PytestDeprecationWarning: The 'junit_family' default value will change to 'xunit2' in pytest 6.0.
-      Add 'junit_family=legacy' to your pytest.ini file to silence this warning and make your suite compatible.
+To use the new format, update your ``pytest.ini``:
 
-In order to silence this warning, users just need to configure the ``junit_family`` option explicitly:
+.. code-block:: ini
+
+    [pytest]
+    junit_family=xunit2
+
+If you discover that your tooling does not support the new format, and want to keep using the
+legacy version, set the option to ``legacy`` instead:
 
 .. code-block:: ini
 
     [pytest]
     junit_family=legacy
 
+By using ``legacy`` you will keep using the legacy/xunit1 format when upgrading to
+pytest 6.0, where the default format will be ``xunit2``.
+
+In order to let users know about the transition, pytest will issue a warning in case
+the ``--junitxml`` option is given in the command line but ``junit_family`` is not explicitly
+configured in ``pytest.ini``.
+
 
 ``funcargnames`` alias for ``fixturenames``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/src/_pytest/deprecated.py b/src/_pytest/deprecated.py
index 1896a05405f..8c9bd9d5c42 100644
--- a/src/_pytest/deprecated.py
+++ b/src/_pytest/deprecated.py
@@ -49,9 +49,9 @@
 )
 
 JUNIT_XML_DEFAULT_FAMILY = PytestDeprecationWarning(
-    "The 'junit_family' default value will change to 'xunit2' in pytest 6.0.\n"
-    "Add 'junit_family=xunit1' to your pytest.ini file to keep the current format "
-    "in future versions of pytest and silence this warning."
+    "The 'junit_family' default value will change to 'xunit2' in pytest 6.0. See:\n"
+    "  https://docs.pytest.org/en/latest/deprecations.html#junit-family-default-value-change-to-xunit2\n"
+    "for more information."
 )
 
 NO_PRINT_LOGS = PytestDeprecationWarning(