diff --git a/README.md b/README.md index f68c9b79..5171e9cd 100644 --- a/README.md +++ b/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). Creative Commons License
LSST DM Developer Guide by Association of Universities for Research in Astronomy, Inc. is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at https://github.com/lsst_dm/dm_dev_guide. diff --git a/conf.py b/conf.py index df93c9c6..f75d2edb 100644 --- a/conf.py +++ b/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 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 `. + +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.