diff --git a/changelog/1149.feature.rst b/changelog/1149.feature.rst
index fec257d5348..9be3376c052 100644
--- a/changelog/1149.feature.rst
+++ b/changelog/1149.feature.rst
@@ -1,4 +1,5 @@
 Pytest no longer accepts prefixes of command-line arguments.
 This was previously allowed where the ``ArgumentParser`` thought it was unambigious,
 because this could be incorrect due to delayed parsing of options for plugins.
+Concretely, you may need to change e.g. ``-ra`` to ``-r=a``.
 See for example issues #1149, #3413, and #4009.
diff --git a/doc/en/customize.rst b/doc/en/customize.rst
index 77217e9d2e3..458a046623c 100644
--- a/doc/en/customize.rst
+++ b/doc/en/customize.rst
@@ -136,7 +136,7 @@ progress output, you can write it into a configuration file:
     # content of pytest.ini or tox.ini
     # setup.cfg files should use [tool:pytest] section instead
     [pytest]
-    addopts = -ra -q
+    addopts = -r=a -q
 
 Alternatively, you can set a ``PYTEST_ADDOPTS`` environment variable to add command
 line options while the environment is in use:
@@ -161,7 +161,7 @@ The actual command line executed is:
 
 .. code-block:: bash
 
-    pytest -ra -q -v -m slow
+    pytest -r=a -q -v -m slow
 
 Note that as usual for other command-line applications, in case of conflicting options the last one wins, so the example
 above will show verbose output because ``-v`` overwrites ``-q``.
diff --git a/doc/en/usage.rst b/doc/en/usage.rst
index acf736f211e..e9d33e7ad72 100644
--- a/doc/en/usage.rst
+++ b/doc/en/usage.rst
@@ -200,7 +200,7 @@ Example:
 
 .. code-block:: pytest
 
-    $ pytest -ra
+    $ pytest -r=a
     =========================== test session starts ============================
     platform linux -- Python 3.x.y, pytest-4.x.y, py-1.x.y, pluggy-0.x.y
     cachedir: $PYTHON_PREFIX/.pytest_cache
diff --git a/testing/test_runner.py b/testing/test_runner.py
index 77fdcecc3fa..7e716d2d72a 100644
--- a/testing/test_runner.py
+++ b/testing/test_runner.py
@@ -758,7 +758,7 @@ def test_foo():
             pass
     """
     )
-    result = testdir.runpytest("-ra")
+    result = testdir.runpytest("-r=a")
     result.stdout.fnmatch_lines(["*just because*"])
     result.stdout.fnmatch_lines(["*collected 0 items / 1 skipped*"])
 
diff --git a/testing/test_skipping.py b/testing/test_skipping.py
index 6bb5f7aff7a..d71629346f6 100644
--- a/testing/test_skipping.py
+++ b/testing/test_skipping.py
@@ -828,7 +828,7 @@ def test_5(fail):
             pass
     """
     )
-    result = testdir.runpytest("-ra")
+    result = testdir.runpytest("-r=a")
     result.stdout.fnmatch_lines(
         [
             "SKIP*four*",
@@ -851,7 +851,7 @@ def test_foo():
             pass
         """,
     )
-    result = testdir.runpytest("-ra")
+    result = testdir.runpytest("-r=a")
     result.stdout.fnmatch_lines(["ERROR*test_foo*"])
 
 
@@ -1145,7 +1145,7 @@ def test_fail():
             assert 0
     """
     )
-    result = testdir.runpytest("-ra")
+    result = testdir.runpytest("-r=a")
     result.stdout.fnmatch_lines(
         [
             "=* FAILURES *=",
diff --git a/testing/test_terminal.py b/testing/test_terminal.py
index f53cb6837bf..548c53fd985 100644
--- a/testing/test_terminal.py
+++ b/testing/test_terminal.py
@@ -1203,7 +1203,7 @@ def test_failure():
             assert 0
     """
     )
-    result = testdir.runpytest("-ra")
+    result = testdir.runpytest("-r=a")
     result.stdout.fnmatch_lines(
         [
             "*= warnings summary =*",
@@ -1230,7 +1230,7 @@ def test_failure():
             assert 0
     """
     )
-    result = testdir.runpytest("-ra")
+    result = testdir.runpytest("-r=a")
     result.stdout.fnmatch_lines(
         [
             "*= warnings summary =*",
diff --git a/tox.ini b/tox.ini
index 7e5b182f69b..00bae0382ec 100644
--- a/tox.ini
+++ b/tox.ini
@@ -121,7 +121,7 @@ commands = python scripts/release.py {posargs}
 
 [pytest]
 minversion = 2.0
-addopts = -ra -p pytester --strict-markers
+addopts = -r=a -p pytester --strict-markers
 rsyncdirs = tox.ini doc src testing
 python_files = test_*.py *_test.py testing/*/*.py
 python_classes = Test Acceptance