Documentation: notes on verbosity & versioning

[sadielbartholomew]

Some documentation commits. Putting these in via PR because I want to do some work on the GH Actions workflow (specifically, get the environment set up so the test_PP_* tests can pass) & want to stick to having triggering with PRs only.

[sadielbartholomew]

Trying again as there were a seg fault which is not a good sign...

[sadielbartholomew]

Hi @davidhassell, it would be good to check a few things with you about the test suite here. Ignore the two initial commits, they are not relevant & I was using them solely as something to have for a PR to run the Actions workflow.

1. Previously the tests requiring recognition of PP files were failing consistently (e.g. from a job yesterday):

   2020-06-16T20:33:24.5417761Z ======================================================================
   2020-06-16T20:33:24.5420931Z ERROR: test_PP_load_stash2standard_name (test_pp.ppTest)
   2020-06-16T20:33:24.5422313Z ----------------------------------------------------------------------
   2020-06-16T20:33:24.5422782Z Traceback (most recent call last):
   2020-06-16T20:33:24.5424959Z   File "/home/runner/work/cf-python/cf-python/cf/read_write/read.py", line 579, in read
   2020-06-16T20:33:24.5425731Z     ftype = file_type(filename)
   2020-06-16T20:33:24.5426784Z   File "/home/runner/work/cf-python/cf-python/cf/read_write/read.py", line 928, in file_type
   2020-06-16T20:33:24.5427757Z     raise IOError("Can't determine format of file {}".format(filename))
   2020-06-16T20:33:24.5428644Z OSError: Can't determine format of file /home/runner/work/cf-python/cf-python/cf/test/wgdos_packed.pp
   2020-06-16T20:33:24.5429006Z 
   2020-06-16T20:33:24.5429418Z During handling of the above exception, another exception occurred:
   2020-06-16T20:33:24.5429747Z 
   2020-06-16T20:33:24.5430148Z Traceback (most recent call last):
   2020-06-16T20:33:24.5431457Z   File "/home/runner/work/cf-python/cf-python/cf/test/test_pp.py", line 48, in test_PP_load_stash2standard_name
   2020-06-16T20:33:24.5431992Z     f = cf.read(self.ppfilename)[0]
   2020-06-16T20:33:24.5433031Z   File "/usr/share/miniconda3/envs/cf-latest/lib/python3.8/site-packages/cfdm/decorators.py", line 146, in verbose_override_wrapper
   2020-06-16T20:33:24.5433574Z     return method_with_verbose_kwarg(self, *args, **kwargs)
   2020-06-16T20:33:24.5434463Z   File "/home/runner/work/cf-python/cf-python/cf/read_write/read.py", line 597, in read
   2020-06-16T20:33:24.5434974Z     raise ValueError(message)
   2020-06-16T20:33:24.5435814Z ValueError: Can't determine format of file /home/runner/work/cf-python/cf-python/cf/test/wgdos_packed.pp
   2020-06-16T20:33:24.5437356Z 
   2020-06-16T20:33:24.5437600Z ======================================================================
   2020-06-16T20:33:24.5437849Z ERROR: test_PP_WGDOS_UNPACKING (test_pp.ppTest)
   2020-06-16T20:33:24.5438457Z ----------------------------------------------------------------------
   2020-06-16T20:33:24.5438699Z Traceback (most recent call last):
   2020-06-16T20:33:24.5439369Z   File "/home/runner/work/cf-python/cf-python/cf/read_write/read.py", line 579, in read
   2020-06-16T20:33:24.5439640Z     ftype = file_type(filename)
   2020-06-16T20:33:24.5440657Z   File "/home/runner/work/cf-python/cf-python/cf/read_write/read.py", line 928, in file_type
   2020-06-16T20:33:24.5441357Z     raise IOError("Can't determine format of file {}".format(filename))
   2020-06-16T20:33:24.5441985Z OSError: Can't determine format of file /home/runner/work/cf-python/cf-python/cf/test/wgdos_packed.pp
   2020-06-16T20:33:24.5442160Z 
   2020-06-16T20:33:24.5442387Z During handling of the above exception, another exception occurred:
   2020-06-16T20:33:24.5442522Z 
   2020-06-16T20:33:24.5442732Z Traceback (most recent call last):
   2020-06-16T20:33:24.5443439Z   File "/home/runner/work/cf-python/cf-python/cf/test/test_pp.py", line 64, in test_PP_WGDOS_UNPACKING
   2020-06-16T20:33:24.5443965Z     f = cf.read(self.ppfilename)[0]
   2020-06-16T20:33:24.5444792Z   File "/usr/share/miniconda3/envs/cf-latest/lib/python3.8/site-packages/cfdm/decorators.py", line 146, in verbose_override_wrapper
   2020-06-16T20:33:24.5445104Z     return method_with_verbose_kwarg(self, *args, **kwargs)
   2020-06-16T20:33:24.5445777Z   File "/home/runner/work/cf-python/cf-python/cf/read_write/read.py", line 597, in read
   2020-06-16T20:33:24.5446085Z     raise ValueError(message)
   2020-06-16T20:33:24.5446710Z ValueError: Can't determine format of file /home/runner/work/cf-python/cf-python/cf/test/wgdos_packed.pp
   2020-06-16T20:33:24.5446871Z 
   2020-06-16T20:33:24.5447097Z ======================================================================
   2020-06-16T20:33:24.5447348Z ERROR: test_read_pp (test_read_write.read_writeTest)
   2020-06-16T20:33:24.5447898Z ----------------------------------------------------------------------
   2020-06-16T20:33:24.5448142Z Traceback (most recent call last):
   2020-06-16T20:33:24.5448799Z   File "/home/runner/work/cf-python/cf-python/cf/read_write/read.py", line 579, in read
   2020-06-16T20:33:24.5449079Z     ftype = file_type(filename)
   2020-06-16T20:33:24.5449755Z   File "/home/runner/work/cf-python/cf-python/cf/read_write/read.py", line 928, in file_type
   2020-06-16T20:33:24.5450447Z     raise IOError("Can't determine format of file {}".format(filename))
   2020-06-16T20:33:24.5450971Z OSError: Can't determine format of file wgdos_packed.pp
   2020-06-16T20:33:24.5451126Z 
   2020-06-16T20:33:24.5451351Z During handling of the above exception, another exception occurred:
   2020-06-16T20:33:24.5451485Z 
   2020-06-16T20:33:24.5451696Z Traceback (most recent call last):
   2020-06-16T20:33:24.5452389Z   File "/home/runner/work/cf-python/cf-python/cf/test/test_read_write.py", line 405, in test_read_pp
   2020-06-16T20:33:24.5452927Z     p = cf.read('wgdos_packed.pp')[0]
   2020-06-16T20:33:24.5453709Z   File "/usr/share/miniconda3/envs/cf-latest/lib/python3.8/site-packages/cfdm/decorators.py", line 146, in verbose_override_wrapper
   2020-06-16T20:33:24.5454024Z     return method_with_verbose_kwarg(self, *args, **kwargs)
   2020-06-16T20:33:24.5454828Z   File "/home/runner/work/cf-python/cf-python/cf/read_write/read.py", line 597, in read
   2020-06-16T20:33:24.5455145Z     raise ValueError(message)
   2020-06-16T20:33:24.5455688Z ValueError: Can't determine format of file wgdos_packed.pp
   2020-06-16T20:33:24.5455823Z 
   2020-06-16T20:33:24.5456345Z ----------------------------------------------------------------------
   2020-06-16T20:33:24.5456585Z Ran 263 tests in 2818.015s
   2020-06-16T20:33:24.5456703Z 
   2020-06-16T20:33:24.5456905Z FAILED (errors=3)
   

   but if I go into the cf/umread_lib/c-lib and run make (I don't think make clean is needed but I could add that in later), as is now done in the workflow here as I added as a new step to the workflow in c045acb, those tests pass (see the test jobs tied to this PR e.g. the one that passes here). This is aligned with my experience locally as I recall that PP files were not able to be read without initially running that make.

   If I remember right (could easily be mistaken though) back when I was quite new to cf-python you mentioned there should be no need to run make to get the PP files recognised. Is that right? If so, this is evidence that that is not in fact the case. Is there something I am doing or assuming incorrectly here, or does this imply a problem somewhere?

2. Now all that fails, and only on the 3.8 run, are a pair of test_geometry tests:

   ======================================================================
   FAIL: test_geometry_interior_ring (test_geometry.DSGTest)
   ----------------------------------------------------------------------
   Traceback (most recent call last):
     File "/home/runner/work/cf-python/cf-python/cf/test/test_geometry.py", line 227, in test_geometry_interior_ring
       self.assertTrue(a.equals(b, verbose=2))
   AssertionError: False is not true
   
   ======================================================================
   FAIL: test_geometry_4 (test_geometry.DSGTest)
   ----------------------------------------------------------------------
   Traceback (most recent call last):
     File "/home/runner/work/cf-python/cf-python/cf/test/test_geometry.py", line 188, in test_geometry_4
       self.assertTrue(a.equals(b, verbose=2))
   AssertionError: False is not true
   
   ----------------------------------------------------------------------
   Ran 263 tests in 2862.750s
   
   FAILED (failures=2)

   This is puzzling me as those tests pass consistently over several runs using Python 3.8 locally. Any idea why they might be failing here, & only on 3.8? Could it be at all related to the make step as above (I wouldn't have thought so)? Are we okay to ignore this? I can always re-run the workflow job to see if they fail again to see if the failure is consistent but I have seen it on the previous run too.

[sadielbartholomew]

Discussed with @davidhassell offline. I'll merge this but open a new Issue regarding the PP file recognition & referencing the comment above to track the potential problem (hopefully the text results still show on merge, regardless they can be accessed via the Actions tab).