Merge pull request #1234 from mhearne-usgs/installfix

Installfix

azure-pipelines.yml

@@ -16,40 +16,30 @@ jobs:
   timeoutInMinutes: 120
   strategy:
     matrix:
-      #Linux_Python38:
-      #imageName: 'ubuntu-latest'
-      #python.version: '3.8'
       Linux_Python39:
         imageName: 'ubuntu-latest'
         python.version: '3.9'
+        install.flags: ''
       Linux_Python310:
         imageName: 'ubuntu-latest'
         python.version: '3.10'
-          #MacOS_11_Python38:
-          #imageName: 'macos-11'
-          #python.version: '3.8'
+        install.flags: '-un -p 3.10'
       MacOS_12_Python39:
         imageName: 'macos-latest'
         python.version: '3.9'
-          #MacOS_12_Python310:
-          #imageName: 'macos-latest'
-          #python.version: '3.10'
+        install.flags: ''
+      MacOS_12_Python310:
+        imageName: 'macos-latest'
+        python.version: '3.10'
+        install.flags: '-un -p 3.10'
       MacOS_11_Python39:
         imageName: 'macos-11'
         python.version: '3.9'
-          #MacOS_11_Python310:
-          #imageName: 'macos-11'
-          #python.version: '3.10'
-          #MacOS_10_15_Python38:
-          #imageName: 'macOS-10.15'
-          #python.version: '3.8'
-      MacOS_10_15_Python39:
-        imageName: 'macOS-10.15'
-        python.version: '3.9'
-          #MacOS_10_15_Python310:
-          #imageName: 'macOS-10.15'
-          #python.version: '3.10'
-
+        install.flags: ''
+      MacOS_11_Python310:
+        imageName: 'macos-11'
+        python.version: '3.10'
+        install.flags: '-un -p 3.10'
   pool:
     vmImage: $(imageName)
 
@@ -80,7 +70,7 @@ jobs:
       echo $(Agent.NAME)
       echo $(python.version)
       echo "Conda is " $CONDA " user is " $USER
-      bash install.sh -p $(python.version)
+      bash install.sh $(install.flags)
     displayName: Create environment
 
   - bash: |

doc_source/manual4_0/sg_contributing.rst

@@ -374,6 +374,79 @@ development should take place within feature branches, and the
 local master branch is updated only by pulling from the upstream
 repository.
 
+Dependency Management
+=====================
+
+A developer may wish to update ShakeMap Python dependencies. For this 
+use case, the install script, included in the repository, has arguments 
+to assist with this process.
+
+The help for the install.sh script (found at the root level of the ShakeMap
+directory) has the following usage help::
+
+  Usage: install.sh [ -u  Update]
+                    [ -t  Run tests ]
+                    [ -p  Set Python version]
+                    [ -n  Don't run tests]
+
+To upgrade to the latest versions of the Python dependencies:
+
+  $ bash install.sh -u
+
+The "-u" option will ignore the platform-specific "spec" file that is 
+included in the repository ("deployment_linux.txt" or "deployment_macos.txt") 
+and create an environment using the "source_environment.yml" file as input. 
+This file may contain some pinning of conda versions in order to avoid conflicts 
+between dependencies. 
+
+Running the install script with the update option will force tests to run. 
+If all of these tests succeed, then a new "spec" file will be created as 
+appropriate to your environment (Linux or MacOS). If ANY of these tests fail,
+this file will not be re-created, and the developer should review the code 
+being tested to determine if the errors can be resolved by either 1) updating
+the code to match changes in dependencies or 2) by pinning the dependencies to
+versions that work with the current state of ShakeMap code. Updating the code  
+is generally the preferred solution, unless the pinning is to recent versions 
+and *higher*. Keeping the ShakeMap code compliant with the most recent versions 
+of dependencies will prevent further errors in the future. 
+
+If the developer is working on a Linux platform, they must then have access to a 
+MacOS platform, or conversely, a MacOS developer must have access to a Linux platform. 
+The developer should run the install script with the "-u" option on *both* platforms, 
+and resolve all issues found on both.
+
+If the developer wants to test the installation with a version of Python higher 
+than the default version found in the install script ("grep DEFAULT_PYVER install.sh") 
+they should use the -p option *together* with the -u option. Given how quickly things 
+change in the Python ecosystem, this is likely to cause errors with tests. Resolve in 
+the same way as described above.
+
+The install script depends on the following files:
+ - source_environment.yml A yaml file with minimal pinning of python dependencies. 
+   This file is only ever an input.
+ - deployment_linux.txt A text file containing urls of Linux conda packages to download.
+   This file is generated by the install script and also used as an input when run with 
+   the update option.
+ - deployment_macos.txt A text file containing urls of MacOS conda packages to download.
+   This file is generated by the install script and also used as an input when run with 
+   the update option.
+ - requirements.txt A text file with the packages that must be installed by pip instead of conda.
+
+ Use cases:
+  - "Deployment" Users who simply wish to install ShakeMap in order to run it and have no
+    interest in development. These users should run `bash install.sh` to create an environment
+    using either the deployment_linux.txt or deployment_macos.txt files as input. To automate
+    the running of tests following the install users can run `bash install.sh -t`, otherwise they
+    can manually run `py.test --cov=.` after the install is complete.
+
+  - "Development" Users who are contributing to ShakeMap development and need to update the ShakeMap 
+    code and the Python dependencies. `bash install.sh -u` will update dependencies, run tests, and 
+    generate a new deployment_<platform>.txt file if the tests are successful. If a developer wants to 
+    update the environment but NOT run tests and NOT generate a new deployment_<platform>.txt file, they
+    can run `bash install.sh -un`. Developers who want to update the Python version from the current
+    default and the dependencies (many Python packages have version-specific builds) can run
+    `bash install.sh -u -p 3.X`. Unless the "-n" option is added, tests will be run and a new 
+    deployment_<platform>.txt file will be created.
 
 Core Modules
 =============

docs/_sources/manual4_0/sg_contributing.rst.txt

@@ -375,6 +375,7 @@ local master branch is updated only by pulling from the upstream
 repository.
 
 
+
 Core Modules
 =============