add AsdfProvisionalAPIWarning

CHANGES.rst

@@ -5,6 +5,9 @@ The ASDF Standard is at v1.6.0
 
 - Discard cache of lazy-loaded block data when it is no longer referenced
   by the tree. [#1280]
+- Add AsdfProvisionalAPIWarning to warn developers of new features that
+  may undergo breaking changes but are likely to be included as stable
+  features (without this warning) in a future version of ASDF [#1295]
 
 2.14.3 (2022-12-15)
 -------------------

asdf/exceptions.py

@@ -21,3 +21,12 @@ class DelimiterNotFoundError(ValueError):
     Indicates that a delimiter was not found when reading or
     seeking through a file.
     """
+
+
+class AsdfProvisionalAPIWarning(AsdfWarning, FutureWarning):
+    """
+    Used for provisional features where breaking API changes might be
+    introduced at any point (including minor releases). These features
+    are likely to be added in a future ASDF version. However, Use of
+    provisional features is highly discouraged for production code.
+    """

docs/asdf/developer_overview.rst

@@ -72,6 +72,12 @@ Support for ASDF core tags has not yet been moved to the new system.  Doing so
 would be a breaking change for users who subclass that code, so we'll need
 to wait until asdf 3.0 to do that.
 
+Some features working toward this goal are available for testing but will raise
+a ``AsdfProvisionalAPIWarning`` when used. This warning indicates that a feature
+may experience breaking API changes (even for minor ASDF releases) and should
+not be trusted in a production environment. It is likely that features that
+raise this warning will become stable and be added to a future ASDF version.
+
 Some terminology and definitions
 --------------------------------