Document using -W with pytest to detect deprecations

docs/development/release-process.md

@@ -21,3 +21,9 @@ SemVer makes it easier to see at a glance how compatible releases are with each
 ## Deprecation policy
 
 A [feature release](#feature-releases) may deprecate a feature, but it will not remove it until the next major release. A deprecation will be clearly documented in the changelog and in the code.
+
+All deprecated features will emit a `SingerDeprecationWarning` when used, so users can raise them as exceptions when running their tests to ensure that they are not using any deprecated features:
+
+```console
+$ pytest -W error::singer_sdk.utils.deprecation.SingerSDKDeprecationWarning
+```

singer_sdk/streams/rest.py

@@ -26,6 +26,7 @@
 )
 from singer_sdk.plugin_base import PluginBase as TapBaseClass
 from singer_sdk.streams.core import Stream
+from singer_sdk.utils.deprecation import SingerSDKDeprecationWarning
 
 if TYPE_CHECKING:
     from backoff.types import Details
@@ -484,7 +485,7 @@ def get_new_paginator(self) -> BaseAPIPaginator:
             A paginator instance.
         """
         if hasattr(self, "get_next_page_token"):
-            warning = DeprecationWarning(
+            warning = SingerSDKDeprecationWarning(
                 "`RESTStream.get_next_page_token` is deprecated and will not be used "
                 + "in a future version of the Meltano Singer SDK. "
                 + "Override `RESTStream.get_new_paginator` instead."

tests/core/test_streams.py

@@ -28,6 +28,7 @@
     Property,
     StringType,
 )
+from singer_sdk.utils.deprecation import SingerSDKDeprecationWarning
 
 CONFIG_START_DATE = "2021-01-01"
 
@@ -461,7 +462,7 @@ def test_next_page_token_jsonpath(
     RestTestStream.next_page_token_jsonpath = path
     stream = RestTestStream(tap)
 
-    with pytest.warns(DeprecationWarning):
+    with pytest.warns(SingerSDKDeprecationWarning):
         paginator = stream.get_new_paginator()
 
     next_page = paginator.get_next(fake_response)