Add a note about providing stable interfaces

README.md

@@ -57,6 +57,6 @@ Remember to preview your published branch by finding it at https://developer.lss
 
 ## License
 
-Copyright 2015-2019 Association of Universities for Research in Astronomy, Inc. (AURA).
+Copyright 2015-2024 Association of Universities for Research in Astronomy, Inc. (AURA).
 
 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">LSST DM Developer Guide</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="http://www.lsst.org" property="cc:attributionName" rel="cc:attributionURL">Association of Universities for Research in Astronomy, Inc.</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />Based on a work at <a xmlns:dct="http://purl.org/dc/terms/" href="https://github.com/lsst_dm/dm_dev_guide" rel="dct:source">https://github.com/lsst_dm/dm_dev_guide</a>.

conf.py

@@ -69,7 +69,7 @@
 
 # General information about the project.
 project = u'LSST DM Developer Guide'
-copyright = u'2016-2023 Association of Universities for Research in Astronomy, Inc. (AURA)'
+copyright = u'2016-2024 Association of Universities for Research in Astronomy, Inc. (AURA)'
 author = u'LSST Data Management'
 
 # The version info for the project you're documenting, acts as replacement for

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.