Merge pull request #272 from NASA-PDS/255_service_upgrade_docs

Documentation for Service Upgrade

README.md

@@ -60,17 +60,10 @@ Create a file in the base directory of the project named `pds_doi_service.ini`;
     url = https://pds.nasa.gov/pds4/pds/v1/PDS4_PDS_JSON_1D00.JSON
     pds_node_identifier = 0001_NASA_PDS_1.pds.Node.pds.name
 
-    [LANDING_PAGES]
-    # template url, arguments are
-    # 1) product_class suffix, after _
-    # 2) lid
-    # 3) vid
-    url = https://pds.nasa.gov/ds-view/pds/view{}.jsp?identifier={}&version={}
-
     [OTHER]
     logging_level = INFO
     doi_publisher = NASA Planetary Data System
-    global_keyword_values = PDS; PDS4;
+    global_keyword_values = PDS,PDS4
     pds_uri = http://pds.nasa.gov/pds4/pds/v1
     transaction_dir = ./transaction_history
     db_file = doi.db

docs/requirements/v21.2.4-dev/REQUIREMENTS.md

@@ -4,187 +4,187 @@ Requirements Summary
 
 # DOI management
 
-## The software shall be capable of accepting a request to create a draft DOI. ([#5](https://github.com/NASA-PDS/pds-doi-service/issues/5)) 
+## The software shall be capable of accepting a request to create a draft DOI. ([#5](https://github.com/NASA-PDS/pds-doi-service/issues/5))
 
 
 This requirement is not impacted by the current version
-## The software shall be capable of accepting a request to reserve a DOI. ([#6](https://github.com/NASA-PDS/pds-doi-service/issues/6)) 
+## The software shall be capable of accepting a request to reserve a DOI. ([#6](https://github.com/NASA-PDS/pds-doi-service/issues/6))
 
 
 This requirement is not impacted by the current version
-## The software shall be capable of accepting a request to release a DOI. ([#7](https://github.com/NASA-PDS/pds-doi-service/issues/7)) 
+## The software shall be capable of accepting a request to release a DOI. ([#7](https://github.com/NASA-PDS/pds-doi-service/issues/7))
 
 
 This requirement is not impacted by the current version
-## The software shall be capable of accepting a request to deactivate a DOI. ([#8](https://github.com/NASA-PDS/pds-doi-service/issues/8)) 
+## The software shall be capable of accepting a request to deactivate a DOI. ([#8](https://github.com/NASA-PDS/pds-doi-service/issues/8))
 
 
 This requirement is not impacted by the current version
-## The software shall be capable of accepting a request to update DOI metadata. ([#9](https://github.com/NASA-PDS/pds-doi-service/issues/9)) 
+## The software shall be capable of accepting a request to update DOI metadata. ([#9](https://github.com/NASA-PDS/pds-doi-service/issues/9))
 
 
 This requirement is not impacted by the current version
-## The software shall be capable of batch processing >1 DOI requests.	 ([#10](https://github.com/NASA-PDS/pds-doi-service/issues/10)) 
+## The software shall be capable of batch processing >1 DOI requests.	 ([#10](https://github.com/NASA-PDS/pds-doi-service/issues/10))
 
 
 This requirement is not impacted by the current version
 # DOI metadata
 
-## The software shall be capable of autonomously generating the minimum set of DOI metadata from PDS4 Collection, Bundle, Document products. ([#11](https://github.com/NASA-PDS/pds-doi-service/issues/11)) 
+## The software shall be capable of autonomously generating the minimum set of DOI metadata from PDS4 Collection, Bundle, Document products. ([#11](https://github.com/NASA-PDS/pds-doi-service/issues/11))
 
 
 This requirement is not impacted by the current version
-## The software shall validate a minimum set of metadata is provided when reserving, releasing, or updating a DOI. This minimum set of metadata will be defined by the PDS DOI Working Group. ([#12](https://github.com/NASA-PDS/pds-doi-service/issues/12)) 
+## The software shall validate a minimum set of metadata is provided when reserving, releasing, or updating a DOI. This minimum set of metadata will be defined by the PDS DOI Working Group. ([#12](https://github.com/NASA-PDS/pds-doi-service/issues/12))
 
 
 This requirement is not impacted by the current version
-## The software shall validate the DOI metadata when reserving, releasing, or updating a DOI. ([#13](https://github.com/NASA-PDS/pds-doi-service/issues/13)) 
+## The software shall validate the DOI metadata when reserving, releasing, or updating a DOI. ([#13](https://github.com/NASA-PDS/pds-doi-service/issues/13))
 
 
 This requirement is not impacted by the current version
 #  DOI interface support
 
-## The software shall maintain a database of PDS DOIs and their current state. ([#14](https://github.com/NASA-PDS/pds-doi-service/issues/14)) 
+## The software shall maintain a database of PDS DOIs and their current state. ([#14](https://github.com/NASA-PDS/pds-doi-service/issues/14))
 
 
 This requirement is not impacted by the current version
-## The software shall maintain the ability to manage DOIs through OSTI ([#15](https://github.com/NASA-PDS/pds-doi-service/issues/15)) 
+## The software shall maintain the ability to manage DOIs through OSTI ([#15](https://github.com/NASA-PDS/pds-doi-service/issues/15))
 
 
 This requirement is not impacted by the current version
-## The software shall maintain the ability to manage DOIs through DataCite. ([#16](https://github.com/NASA-PDS/pds-doi-service/issues/16)) 
+## The software shall maintain the ability to manage DOIs through DataCite. ([#16](https://github.com/NASA-PDS/pds-doi-service/issues/16))
 
 
 This requirement is not impacted by the current version
 # DOI-management
 
-## The software shall provide a Status capability that will allow a user to query for the current status of a DOI ([#30](https://github.com/NASA-PDS/pds-doi-service/issues/30)) 
+## The software shall provide a Status capability that will allow a user to query for the current status of a DOI ([#30](https://github.com/NASA-PDS/pds-doi-service/issues/30))
 
 
 This requirement is not impacted by the current version
-## The software shall provide the capability of producing a DOI Status Report based upon a user-specified query ([#35](https://github.com/NASA-PDS/pds-doi-service/issues/35)) 
+## The software shall provide the capability of producing a DOI Status Report based upon a user-specified query ([#35](https://github.com/NASA-PDS/pds-doi-service/issues/35))
 
 
 This requirement is not impacted by the current version
 # default
 
-## As a node operator, I want to include a DOI as a related identifier in the DOI metadata for parent PDS4 products. ([#69](https://github.com/NASA-PDS/pds-doi-service/issues/69)) 
+## As a node operator, I want to include a DOI as a related identifier in the DOI metadata for parent PDS4 products. ([#69](https://github.com/NASA-PDS/pds-doi-service/issues/69))
 
 
 This requirement is not impacted by the current version
-## As a node user, I want the LIDVID associated with a DOI to be automatically updated for accumulating bundles / collections. ([#97](https://github.com/NASA-PDS/pds-doi-service/issues/97)) 
+## As a node user, I want the LIDVID associated with a DOI to be automatically updated for accumulating bundles / collections. ([#97](https://github.com/NASA-PDS/pds-doi-service/issues/97))
 
 
 This requirement is not impacted by the current version
-## As the PDS, I want to mint DOIs through DataCite ([#103](https://github.com/NASA-PDS/pds-doi-service/issues/103)) 
+## As the PDS, I want to mint DOIs through DataCite ([#103](https://github.com/NASA-PDS/pds-doi-service/issues/103))
 
 
 This requirement is not impacted by the current version
-## Develop DOI Service - Registry integration component for accumulating bundles ([#111](https://github.com/NASA-PDS/pds-doi-service/issues/111)) 
+## Develop DOI Service - Registry integration component for accumulating bundles ([#111](https://github.com/NASA-PDS/pds-doi-service/issues/111))
 
 
 This requirement is not impacted by the current version
-## As a user, I want to see the lidvid of my DOIs in the email report ([#167](https://github.com/NASA-PDS/pds-doi-service/issues/167)) 
+## As a user, I want to see the lidvid of my DOIs in the email report ([#167](https://github.com/NASA-PDS/pds-doi-service/issues/167))
 
 
 This requirement is not impacted by the current version
-## As an operator, I want to reserve a DOI through DataCite ([#171](https://github.com/NASA-PDS/pds-doi-service/issues/171)) 
+## As an operator, I want to reserve a DOI through DataCite ([#171](https://github.com/NASA-PDS/pds-doi-service/issues/171))
 
 
 This requirement is not impacted by the current version
-## As an operator, I want query for one or more minted DOIs from DataCite ([#172](https://github.com/NASA-PDS/pds-doi-service/issues/172)) 
+## As an operator, I want query for one or more minted DOIs from DataCite ([#172](https://github.com/NASA-PDS/pds-doi-service/issues/172))
 
 
 This requirement is not impacted by the current version
-## As an operator, I want to query for a DOI's change history through DataCite ([#173](https://github.com/NASA-PDS/pds-doi-service/issues/173)) 
+## As an operator, I want to query for a DOI's change history through DataCite ([#173](https://github.com/NASA-PDS/pds-doi-service/issues/173))
 
 
 This requirement is not impacted by the current version
-## As an operator, I want to release a DOI through DataCite ([#174](https://github.com/NASA-PDS/pds-doi-service/issues/174)) 
+## As an operator, I want to release a DOI through DataCite ([#174](https://github.com/NASA-PDS/pds-doi-service/issues/174))
 
 
 This requirement is not impacted by the current version
-## As an operator, I want to update DOI metadata through DataCite ([#175](https://github.com/NASA-PDS/pds-doi-service/issues/175)) 
+## As an operator, I want to update DOI metadata through DataCite ([#175](https://github.com/NASA-PDS/pds-doi-service/issues/175))
 
 
 This requirement is not impacted by the current version
-## As an API user, I want to have pagination that is consistent with the PDS API. ([#176](https://github.com/NASA-PDS/pds-doi-service/issues/176)) 
+## As an API user, I want to have pagination that is consistent with the PDS API. ([#176](https://github.com/NASA-PDS/pds-doi-service/issues/176))
 
 
 This requirement is not impacted by the current version
-## As an API user I want to filter on lidvids with wildcards ([#177](https://github.com/NASA-PDS/pds-doi-service/issues/177)) 
+## As an API user I want to filter on lidvids with wildcards ([#177](https://github.com/NASA-PDS/pds-doi-service/issues/177))
 
 
 This requirement is not impacted by the current version
-## As an API user I want to filter on PDS3 Data Set IDs with wildcards ([#180](https://github.com/NASA-PDS/pds-doi-service/issues/180)) 
+## As an API user I want to filter on PDS3 Data Set IDs with wildcards ([#180](https://github.com/NASA-PDS/pds-doi-service/issues/180))
 
 
 This requirement is not impacted by the current version
-## As a user of the API, I want to see the DOI's title when I go GET /dois request ([#183](https://github.com/NASA-PDS/pds-doi-service/issues/183)) 
+## As a user of the API, I want to see the DOI's title when I go GET /dois request ([#183](https://github.com/NASA-PDS/pds-doi-service/issues/183))
 
 
 This requirement is not impacted by the current version
-## As an API user, I want to always have an update date for the DOIs ([#184](https://github.com/NASA-PDS/pds-doi-service/issues/184)) 
+## As an API user, I want to always have an update date for the DOIs ([#184](https://github.com/NASA-PDS/pds-doi-service/issues/184))
 
 
 This requirement is not impacted by the current version
-## As a SA, I want the operational deployment of the service to be secure ([#187](https://github.com/NASA-PDS/pds-doi-service/issues/187)) 
+## As a SA, I want the operational deployment of the service to be secure ([#187](https://github.com/NASA-PDS/pds-doi-service/issues/187))
 
 
 This requirement is not impacted by the current version
-## As a user, I want the application to support the history of PDS's DOIs, especially the one created for PDS3 products ([#192](https://github.com/NASA-PDS/pds-doi-service/issues/192)) 
+## As a user, I want the application to support the history of PDS's DOIs, especially the one created for PDS3 products ([#192](https://github.com/NASA-PDS/pds-doi-service/issues/192))
 
 
 This requirement is not impacted by the current version
-## As a system administrator, I want to be able to deploy pds_doi_service with python 3.6 ([#197](https://github.com/NASA-PDS/pds-doi-service/issues/197)) 
+## As a system administrator, I want to be able to deploy pds_doi_service with python 3.6 ([#197](https://github.com/NASA-PDS/pds-doi-service/issues/197))
 
 
 This requirement is not impacted by the current version
-## As a user, I want to use the API with ids containing a slash (/) ([#198](https://github.com/NASA-PDS/pds-doi-service/issues/198)) 
+## As a user, I want to use the API with ids containing a slash (/) ([#198](https://github.com/NASA-PDS/pds-doi-service/issues/198))
 
 
 This requirement is not impacted by the current version
-## As an operator, I want to know what version of the software I am running ([#200](https://github.com/NASA-PDS/pds-doi-service/issues/200)) 
+## As an operator, I want to know what version of the software I am running ([#200](https://github.com/NASA-PDS/pds-doi-service/issues/200))
 
 
 This requirement is not impacted by the current version
-## As an operator, I want to know how to deploy and use the API from the Sphinx documentation ([#201](https://github.com/NASA-PDS/pds-doi-service/issues/201)) 
+## As an operator, I want to know how to deploy and use the API from the Sphinx documentation ([#201](https://github.com/NASA-PDS/pds-doi-service/issues/201))
 
 
 This requirement is not impacted by the current version
-## As an operator, I want one place to go for all DOI Service / API / UI documentation ([#202](https://github.com/NASA-PDS/pds-doi-service/issues/202)) 
+## As an operator, I want one place to go for all DOI Service / API / UI documentation ([#202](https://github.com/NASA-PDS/pds-doi-service/issues/202))
 
 
 This requirement is not impacted by the current version
-## As a user of the command line, I don't want to see all the log info in the stdout ([#206](https://github.com/NASA-PDS/pds-doi-service/issues/206)) 
+## As a user of the command line, I don't want to see all the log info in the stdout ([#206](https://github.com/NASA-PDS/pds-doi-service/issues/206))
 
 
 This requirement is not impacted by the current version
-## As a command-line user, I want to be suggested to use -f option when a Warning exception is raised ([#207](https://github.com/NASA-PDS/pds-doi-service/issues/207)) 
+## As a command-line user, I want to be suggested to use -f option when a Warning exception is raised ([#207](https://github.com/NASA-PDS/pds-doi-service/issues/207))
 
 
 This requirement is not impacted by the current version
-## As a user, I want to run the commandline on windows ([#212](https://github.com/NASA-PDS/pds-doi-service/issues/212)) 
+## As a user, I want to run the commandline on windows ([#212](https://github.com/NASA-PDS/pds-doi-service/issues/212))
 
 
 This requirement is not impacted by the current version
-## As a user, I want to search dois without case sensitiveness ([#223](https://github.com/NASA-PDS/pds-doi-service/issues/223)) 
+## As a user, I want to search dois without case sensitiveness ([#223](https://github.com/NASA-PDS/pds-doi-service/issues/223))
 
 
 This requirement is not impacted by the current version
-## As a user, I would like to include licensing information with all PDS DOIs ([#224](https://github.com/NASA-PDS/pds-doi-service/issues/224)) 
+## As a user, I would like to include licensing information with all PDS DOIs ([#224](https://github.com/NASA-PDS/pds-doi-service/issues/224))
 
 
 This requirement is not impacted by the current version
-## As an admistrator of the application,  I want to restrict access to API by specific referrer ([#228](https://github.com/NASA-PDS/pds-doi-service/issues/228)) 
+## As an admistrator of the application,  I want to restrict access to API by specific referrer ([#228](https://github.com/NASA-PDS/pds-doi-service/issues/228))
 
 
 This requirement is not impacted by the current version
-## As a user, I want to include related DOIs in DOI metadata ([#232](https://github.com/NASA-PDS/pds-doi-service/issues/232)) 
+## As a user, I want to include related DOIs in DOI metadata ([#232](https://github.com/NASA-PDS/pds-doi-service/issues/232))
 
 
 This requirement is not impacted by the current version
-## As a PDS Operator, I want to perform a bulk update of a specific field across many DOI records ([#257](https://github.com/NASA-PDS/pds-doi-service/issues/257)) 
+## As a PDS Operator, I want to perform a bulk update of a specific field across many DOI records ([#257](https://github.com/NASA-PDS/pds-doi-service/issues/257))
 
 
-This requirement is not impacted by the current version
+This requirement is not impacted by the current version

docs/source/installation/index.rst

@@ -154,6 +154,31 @@ your virtual environment::
 
   pip install --upgrade pds-doi-service
 
+Upgrades to the PDS DOI Service should typically not affect any existing transaction
+database, transaction history, or INI configuration settings. If an instance of
+the PDS DOI API is running, for example in a ``screen`` session, it is recommended that
+it be terminated before performing an upgrade.
+
+.. note::
+
+    An update to an existing virtualenv installation of the PDS DOI Service may fail
+    if the underlying minimum required Python version has changed. If so, a new
+    virtual environment should be created using the required version of Python, after
+    which the latest version of the Service may be installed into it. Consult the
+    installation instructions above on how to create a new virtual environment.
+
+..  note::
+
+    In rare circumstances, an upgrade may invalidate an existing transaction
+    database if the update includes a change to the underlying schema. Any such changes
+    will be clearly identified in the release notes for the version of the service.
+    The ``pds-doi-init`` script may be used in these circumstances to rebuild a fresh
+    transaction database and transaction history based on what is available on DataCite.
+    For this reason, it is recommended that any outstanding draft or review DOI
+    requests are finalized and released before performing an upgrade which invalidates
+    the transaction database. Consult the `usage`_ documentation for more details
+    on running ``pds-doi-init``.
+
 
 .. References:
 .. _usage: ../usage/index.html