Improve user guidance regarding --resultlog deprecation

_pytest/deprecated.py

@@ -26,7 +26,10 @@ class RemovedInPytest4Warning(DeprecationWarning):
 
 GETFUNCARGVALUE = "use of getfuncargvalue is deprecated, use getfixturevalue"
 
-RESULT_LOG = '--result-log is deprecated and scheduled for removal in pytest 4.0'
+RESULT_LOG = (
+    '--result-log is deprecated and scheduled for removal in pytest 4.0.\n'
+    'See https://docs.pytest.org/en/latest/usage.html#creating-resultlog-format-files for more information.'
+)
 
 MARK_INFO_ATTRIBUTE = RemovedInPytest4Warning(
     "MarkInfo objects are deprecated as they contain the merged marks"

changelog/2739.trivial

@@ -0,0 +1 @@
+Improve user guidance regarding ``--resultlog`` deprecation.

doc/en/usage.rst

@@ -311,6 +311,13 @@ Creating resultlog format files
 
     This option is rarely used and is scheduled for removal in 4.0.
 
+    An alternative for users which still need similar functionality is to use the
+    `pytest-tap <https://pypi.python.org/pypi/pytest-tap>`_ plugin which provides
+    a stream of test data.
+
+    If you have any concerns, please don't hesitate to
+    `open an issue <https://github.com/pytest-dev/pytest/issues>`_.
+
 To create plain-text machine-readable result files you can issue::
 
     pytest --resultlog=path

testing/deprecated_test.py

@@ -78,4 +78,7 @@ def test():
             pass
     ''')
     result = testdir.runpytest('--result-log=%s' % testdir.tmpdir.join('result.log'))
-    result.stdout.fnmatch_lines(['*--result-log is deprecated and scheduled for removal in pytest 4.0*'])
+    result.stdout.fnmatch_lines([
+        '*--result-log is deprecated and scheduled for removal in pytest 4.0*',
+        '*See https://docs.pytest.org/*/usage.html#creating-resultlog-format-files for more information*',
+    ])