From 067328abacd196931d3085a46f37e322e6c156f9 Mon Sep 17 00:00:00 2001
From: Zac-HD <zac.hatfield.dodds@gmail.com>
Date: Sun, 17 Mar 2019 10:54:22 +1100
Subject: [PATCH] Expand docs about registering markers

---
 changelog/4826.feature.rst |  2 ++
 doc/en/mark.rst            | 23 +++++++++++++++--------
 doc/en/writing_plugins.rst | 24 ++++++++++++++++++++++++
 3 files changed, 41 insertions(+), 8 deletions(-)
 create mode 100644 changelog/4826.feature.rst

diff --git a/changelog/4826.feature.rst b/changelog/4826.feature.rst
new file mode 100644
index 00000000000..2afcba1ad8e
--- /dev/null
+++ b/changelog/4826.feature.rst
@@ -0,0 +1,2 @@
+A warning is now emitted when unknown marks are used as a decorator.
+This is often due to a typo, which can lead to silently broken tests.
diff --git a/doc/en/mark.rst b/doc/en/mark.rst
index e841a6780d6..ca2e870213f 100644
--- a/doc/en/mark.rst
+++ b/doc/en/mark.rst
@@ -26,14 +26,15 @@ which also serve as documentation.
     :ref:`fixtures <fixtures>`.
 
 
-Raising errors on unknown marks: --strict
------------------------------------------
+.. _unknown-marks:
 
-When the ``--strict`` command-line flag is passed, any unknown marks applied
-with the ``@pytest.mark.name_of_the_mark`` decorator will trigger an error.
-Marks defined or added by pytest or by a plugin will not trigger an error.
+Raising errors on unknown marks
+-------------------------------
 
-Marks can be registered in ``pytest.ini`` like this:
+Unknown marks applied with the ``@pytest.mark.name_of_the_mark`` decorator
+will always emit a warning, in order to avoid silently doing something
+surprising due to mis-typed names.  You can disable the warning for custom
+marks by registering them in ``pytest.ini`` like this:
 
 .. code-block:: ini
 
@@ -42,8 +43,11 @@ Marks can be registered in ``pytest.ini`` like this:
         slow
         serial
 
-This can be used to prevent users mistyping mark names by accident. Test suites that want to enforce this
-should add ``--strict`` to ``addopts``:
+When the ``--strict`` command-line flag is passed, any unknown marks applied
+with the ``@pytest.mark.name_of_the_mark`` decorator will trigger an error.
+Marks added by pytest or by a plugin instead of the decorator will not trigger
+the warning or this error.  Test suites that want to enforce a limited set of
+markers can add ``--strict`` to ``addopts``:
 
 .. code-block:: ini
 
@@ -53,6 +57,9 @@ should add ``--strict`` to ``addopts``:
         slow
         serial
 
+Third-party plugins should always :ref:`register their markers <registering-markers>`
+so that they appear in pytest's help text and do not emit warnings.
+
 
 .. _marker-revamp:
 
diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst
index bc1bcda0e05..fd75d81370a 100644
--- a/doc/en/writing_plugins.rst
+++ b/doc/en/writing_plugins.rst
@@ -286,6 +286,30 @@ the plugin manager like this:
 If you want to look at the names of existing plugins, use
 the ``--trace-config`` option.
 
+
+.. _registering-markers:
+
+Registering custom markers
+--------------------------
+
+If your plugin uses any markers, you should register them so that they appear in
+pytest's help text and do not :ref:`cause spurious warnings <unknown-marks>`.
+For example, the following plugin would register ``cool_marker`` and
+``mark_with`` for all users:
+
+.. code-block:: python
+
+    def pytest_configure(config):
+        config.addinivalue_line(
+            "markers",
+            "cool_marker: this one is for cool tests.",
+        )
+        config.addinivalue_line(
+            "markers",
+            "mark_with(arg, arg2): this marker takes arguments.",
+        )
+
+
 Testing plugins
 ---------------