From e328c25f3d321308cc3532f01f55fc391f461ff6 Mon Sep 17 00:00:00 2001
From: Arun Kannawadi <arunkannawadi@astro.princeton.edu>
Date: Thu, 10 Oct 2024 06:30:55 -0400
Subject: [PATCH] Add a note about providing stable interfaces

upon transferring code between packages.
---
 stack/transferring-code.rst | 52 +++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/stack/transferring-code.rst b/stack/transferring-code.rst
index ac90b424..0ee23860 100644
--- a/stack/transferring-code.rst
+++ b/stack/transferring-code.rst
@@ -25,6 +25,9 @@ the following procedure should be used:
     #. Merge the transfer branch back to the regular issue branch using
        ``--no-ff`` to preserve the transfer branch name in the merge commit.
 
+    #. Make the appropriate changes to support continued import of public interfaces from the origin
+       repository with a deprecation warning. See :ref:`providing-stable-interfaces` for more details.
+
 #. In the destination repository:
 
     #. Create the usual ``tickets/DM-XXXX`` issue branch.
@@ -70,3 +73,52 @@ See `RFC-33`_ for the motivation and discussion behind this policy.
 
 .. _RFC-33: https://jira.lsstcorp.org/browse/rfc-33
 .. _DM Stack Package History: https://confluence.lsstcorp.org/display/DM/DM+Stack+Package+History
+
+
+.. _providing-stable-interfaces:
+
+Providing Stable Interfaces
+===========================
+
+Transferring code between packages is a breaking change and stable interfaces should be provided on a
+best-effort basis to support external users.
+If the origin repository is downstream of the destination (as is typically the case),
+this can be achieved by importing code from the destination repository with an alias,
+trivially repackaging it following the deprecation procedure described in
+:doc:`Deprecating Interfaces <deprecating-interfaces>`.
+
+As an example, if a Python class ``ConfigurableAction`` is moved from package ``analysis_tools`` (downstream) to ``pex_config`` (upstream),
+
+.. code-block:: python
+
+    from lsst.pex.config import ConfigurableAction as ConfigurableActionNew
+    from depecated.sphinx import deprecated
+
+    __all__ = ["ConfigurableAction"]
+
+    @deprecated(reason="Moved to lsst.pex.config",
+                version="v22.0",
+                category=FutureWarning)
+    class ConfigurableAction(ConfigurableActionNew):
+        pass
+
+In the relative less common case of moving code downstream, the following pattern can be used:
+
+.. code-block:: python
+
+    import warnings
+
+    try:
+        from lsst.drp.tasks.assemble_coadd import *  # noqa: F401, F403
+    except ImportError as error:
+        error.msg += ". Please import the coaddition tasks from drp_tasks package."
+        raise error
+    finally:
+        warnings.warn("lsst.pipe.tasks.assembleCoadd is deprecated and will be removed after v27; "
+                      "Please use lsst.drp.tasks.assemble_coadd instead.",
+                      DeprecationWarning,
+                      stacklevel=2
+                      )
+
+This allows the code to be imported from the old location (with a deprecation warning) with a fully built
+version of the Science Pipelines, but does not introduces cyclic dependencies during the build process.