diff --git a/communications/slack-culture.rst b/communications/slack-culture.rst index 0a9b6782..bf660ad3 100644 --- a/communications/slack-culture.rst +++ b/communications/slack-culture.rst @@ -7,7 +7,7 @@ Slack Culture Slack is Rubin Observatory's real-time chat platform. It is used by project staff and science collaboration members, who can view and join all public channels. Partnering users and projects may also be allowed to join specific channels as guests. -(Ask a Slack admin or ask in ``#help-slack`` if you need a guest added to a channel or want to share a channel with another project/organization.) +(Ask a Slack admin or ask in ``#slack-usage-help`` if you need a guest added to a channel or want to share a channel with another project/organization.) Teams may evolve different cultures around the use of Slack. In addition, different types of channels may work in different ways. @@ -257,7 +257,7 @@ The same general considerations apply, however. Slack has a concept of user groups that can be notified instead of an entire channel that has members outside that group. If you can use such a group rather than ``@channel`` or ``@here``, that is preferred. -If you need to have a group created because you have a routine need to @-mention them, contact a Slack admin (e.g. via ``#help-slack``) +If you need to have a group created because you have a routine need to @-mention them, contact a Slack admin (e.g. via ``#slack-usage-help``) @-mentioning a particular user notifies that user and adds the message to their "Mentions & reactions" list. Be aware of the person's timezone before @-mentioning them. diff --git a/stack/transferring-code.rst b/stack/transferring-code.rst index ac90b424..a408bbd7 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 `TreecorrConfig` is moved from package `origin` to package `destination`, + +.. code-block:: python + + from lsst.destination import TreecorrConfig as TreecorrConfigNew + from depecated.sphinx import deprecated + + __all__ = ["TreecorrConfig", ...] + + @deprecated(reason="Moved to lsst.destination", + version="v22.0", + category=FutureWarning) + class TreecorrConfig(TreecorrConfigNew): + 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.