List dependencies. Add help text.

docs/practices/ci_testing.rst

@@ -28,4 +28,27 @@ template that uses GitHub as a repository will automatically have CI enabled.
 
 The ``.github/workflows/smoke-test.yml`` file configures the scheduled smoke test.
 It uses standard cron notation to start the job at 0645 every day. This time was 
-selected to be a little far away from an hour break, when most tests would likely run.
+selected to be a little far away from an hour break, when most tests would likely run.
+
+Version culprit
+-------------------------------------------------------------------------------
+
+If you want some help tracking down your failures, looking for upstream package
+updates is a good place to start. The smoke test has a "List dependencies" stage
+that will print out all packages installed through pip and their installed versions.
+
+1. Find the last successful run of the smoke test
+   1. github repo -> Actions
+   2. "Unit test smoke test"
+   3. Scroll until you find a green check
+   4. Pick a python versioned build
+   5. Expand "List dependencies"
+   6. Cut'n'paste the list to a file, e.g. "pass.txt"
+2. Find a failed run.
+   1. From the "Unit test smoke test" page, find the first red check
+   2. Pick a python versioned build
+   3. Expand "List dependencies"
+   4. Cut'n'paste the list to a file, e.g. "fail.txt"
+3. Diff those lists
+   1. e.g. ``diff pass.txt fail.txt``
+   2. Or use an online diff tool like https://www.diffchecker.com/

python-project-template/.github/workflows/smoke-test.yml

@@ -1,5 +1,7 @@
 # This workflow will run daily at 06:45.
 # It will install Python dependencies and run tests with a variety of Python versions.
+# See documentation for help debugging smoke test issues:
+#    https://lincc-ppt.readthedocs.io/en/latest/practices/ci_testing.html#version-culprit
 
 name: Unit test smoke test
 
@@ -28,6 +30,9 @@ jobs:
         pip install .
         pip install .[dev]
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: List dependencies
+      run: |
+        pip list
     - name: Run unit tests with pytest
       run: |
         python -m pytest tests