JP-2986 CRDS PUB deprecation notice and transition documentation (#7342)

* setup deprecation page

* link to the deprecation page

* include deprecation in the toc

* update changelog

* update jdocs link

* yet another change to the jdocs link

CHANGES.rst

@@ -1,4 +1,12 @@
-1.8.2 (2022-10-19)
+1.8.3 (unreleased)
+==================
+
+documentation
+-------------
+
+- CRDS PUB deprecation notice and transition documentation [#7342]
+
+1.8.2 (2022-10-20)
 ==================
 
 set_telescope_pointing

docs/index.rst

@@ -4,6 +4,12 @@
 
 :ref:`genindex`  |  :ref:`modindex`
 
+.. warning::
+
+   As of November 10, 2022, the process of deprecating the CRDS PUB Server will start.
+
+   For details, refer to the :ref:`pub-deprecation` page.
+
 ============
 Installation
 ============
@@ -68,6 +74,7 @@ User Manual
    :maxdepth: 2
 
    jwst/introduction.rst
+   jwst/pub_deprecation.rst
 
 
 ===========================

docs/jwst/introduction.rst

@@ -47,6 +47,13 @@ described within the table at
 CRDS
 ====
 
+.. warning::
+
+   As of November 10, 2022, the process of deprecating the CRDS PUB Server will start.
+
+   For details, refer to the :ref:`pub-deprecation` page.
+
+
 CRDS reference file mappings are usually set by default to always give access
 to the most recent reference file deliveries and selection rules. On
 occasion it might be necessary or desirable to use one of the non-default
@@ -68,17 +75,6 @@ a header keyword in the output data file. The keyword names use the syntax
 "R_<ref>", where <ref> corresponds to a 6-character version of the reference
 file type, such as ``R_DARK``, ``R_LINEAR``, and ``R_PHOTOM``.
 
-There are two servers available:
-
-  - JWST OPS: https://jwst-crds.stsci.edu
-  - JWST PUB: https://jwst-crds-pub.stsci.edu
-
-JWST OPS supports the automatic processing pipeline at STScI. JWST PUB supports
-the latest public release of the `jwst` package. Most often, the reference
-contexts are one and the same. Regardless, if one wishes to calibrate using the
-same exact information as the automatic processing, use JWST OPS. Otherwise, use
-of JWST PUB is recommended.
-
 Inside the STScI network, the pipeline defaults the CRDS setup to use JWST OPS with no modifications.
 To run the pipeline outside the STScI network or to use a different server, CRDS must be configured by setting
 two environment variables:
@@ -93,13 +89,6 @@ To setup to use JWST OPS, use the following settings:
     export CRDS_PATH=$HOME/crds_cache/jwst_ops
     export CRDS_SERVER_URL=https://jwst-crds.stsci.edu
 
-To setup to use JWST PUB, use the following settings:
-
-::
-
-    export CRDS_PATH=$HOME/crds_cache/jwst_pub
-    export CRDS_SERVER_URL=https://jwst-crds-pub.stsci.edu
-
 .. _strun_command_line:
 
 Running From the Command Line

docs/jwst/pub_deprecation.rst

@@ -0,0 +1,71 @@
+.. _pub-deprecation:
+
+CRDS PUB Server Freeze and Deprecation
+======================================
+
+Why and When
+------------
+
+As of November 10, 2022, all observers should use the standard CRDS OPS server
+for JWST calibration reference files:
+
+`https://jwst-crds.stsci.edu <https://jwst-crds.stsci.edu>`_
+
+The PUB server:
+
+`https://jwst-crds-pub.stsci.edu <https://jwst-crds-pub.stsci.edu>`_
+
+was set up in anticipation of rapid reference file updates during commissioning
+and Cycle 1. However, due to the trouble-free commissioning process,
+the smooth transition to science operations, and the subsequent
+confusion that has resulted from having two servers, it has been
+decided that the PUB server is no longer needed and will be
+decommissioned. To make this transition as smooth as possible, this
+update will take place in stages.
+
+On November 10, 2022, all observers should begin to transition to using only the CRDS
+OPS server, `https://jwst-crds.stsci.edu <https://jwst-crds.stsci.edu>`_. See
+the :ref:`software documentation <pub-deprecation-transition>` for
+instructions about how to configure CRDS.
+
+In mid-November, the PUB server will be frozen and a notification will be sent via the
+reference file mailing lists and the JWST Observer News mailing list.
+
+On December 2nd, access to the PUB server will no longer be available externally.
+The frozen PUB database will be maintained internally for 3 months. On March 1, the PUB server will
+be fully decommissioned and the institute will
+retain an internal archive of the maps and calibration reference files.
+Observers who wish to use historical files from the PUB server in the future will need to file a
+JWST Pipeline help desk ticket to access the information.
+
+Part of the decommissioning process will include establishing guidance for how best to
+maintain reproducibility for new papers and for already-published papers that used the PUB server. This information
+will be included in the new JDox page:
+
+`How to Cite Your Data Reduction and Reference Files <https://jwst-docs.stsci.edu/jwst-science-calibration-pipeline-overview/jwst-data-calibration-reference-files>`_
+
+
+.. _pub-deprecation-transition:
+
+Transition Procedure
+--------------------
+
+If using the PUB server, there are two simple tasks that need to be done to
+ensure a successful transition from using the PUB server to the JWST OPS server.
+
+First, the folder containing the local CRDS cache, pointed to by the environment
+variable CRDS_PATH, should be cleared. Under Linux-like systems, the command is
+
+::
+
+   $ rm -rf $CRDS_PATH/*
+
+Second, ensure that the environment variable CRDS_SERVER_URL is pointing to the
+JWST OPS server, https://jwst-crds.stsci.edu:
+
+::
+
+   $ export CRDS_SERVER_URL=https://jwst-crds.stsci.edu
+
+Following these two steps ensures that further calibration processing will use
+references from the standard CRDS server.