Set minimum supported version to GMT>=6.4.0

[seisman]

Description of proposed changes

In commit 539f3e8, I removed the codes for compatibility with GMT 6.3.0. After that, I manually triggered the "GMT Legacy Tests" workflow at https://github.com/GenericMappingTools/pygmt/actions/runs/11010826577. The CI job for GMT 6.3 no longer works because API_BIN_VERSION was added in GMT 6.4.0.

Error: ession [ERROR]: Unrecognized keyword API_BIN_VERSION
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/home/runner/work/pygmt/pygmt/pygmt/_show_versions.py", line [13](https://github.com/GenericMappingTools/pygmt/actions/runs/11010826577/job/30573600010#step:6:14)7, in show_versions
    lines.extend([f"  {key}: {val}" for key, val in _get_clib_info().items()])
  File "/home/runner/work/pygmt/pygmt/pygmt/_show_versions.py", line 29, in _get_clib_info
    return ses.info
  File "/home/runner/work/pygmt/pygmt/pygmt/clib/session.py", line 202, in info
    self._info["binary version"] = self.get_default("API_BIN_VERSION")
  File "/home/runner/work/pygmt/pygmt/pygmt/clib/session.py", line 500, in get_default
    raise GMTCLibError(msg)
pygmt.exceptions.GMTCLibError: Error getting value for 'API_BIN_VERSION' (error code 68).
make: *** [Makefile:35: _runtest] Error 1

The initial plan is to drop GMT 6.3 support in PyGMT v0.14.0, so we should remove any GMT 6.3 compatibility codes and GMT 6.3 from the CI matrix.

Then, the question is, do we want to revert changes in pygmt/clib/session.py so that most PyGMT functionality still works with GMT 6.3? In this case, GMT 6.3 is still allowed for future PyGMT versions, but there is no guarantee that all PyGMT functionalities work as expected. [Edit: Partially reverted in b0e6c69].

In b0e6c69, I updated pygmt/clib/session.py so that PyGMT works for GMT 6.3-6.5 (also have to temporarily revert test_grdfill.py in c6860b2 because it's known to crash with GMT 6.3). In the CI runs at https://github.com/GenericMappingTools/pygmt/actions/runs/11013102550, most tests still pass, except a few that are expected to fail.

In 33c1061, I removed GMT 6.3 for the testing CI matrix so GMT 6.3 is no longer tested, although PyGMT is still compatible with it. Then the question is whether we want to drop GMT 6.3 support completely. I think we have three options:

1. Bump required_gmt_version from 6.3.0 to 6.4.0, which means that people who use GMT 6.3 will see the GMTVersionError exception
2. Keep required_gmt_version="6.3.0" and add a note like "PyGMT requires GMT>=6.3.0 but only GMT 6.4-6.5 are fully tested" on the installation page.
3. Have two variables like required_gmt_version="6.4.0" and minimum_required_version="6.3.0", and raise the GMTVersionError for GMT<6.3.0 and raise an warning like "GMT 6.3.0 is not fully tested." for GMT=6.3.0.

Thoughts?

[seisman]

3. Have two variables like required_gmt_version="6.4.0" and minimum_required_version="6.3.0", and raise the GMTVersionError for GMT<6.3.0 and raise an warning like "GMT 6.3.0 is not fully tested." for GMT=6.3.0.

I'm inclined to option 3. What do you think @GenericMappingTools/pygmt-maintainers?

[weiji14]

3. Have two variables like required_gmt_version="6.4.0" and minimum_required_version="6.3.0", and raise the GMTVersionError for GMT<6.3.0 and raise an warning like "GMT 6.3.0 is not fully tested." for GMT=6.3.0.

I'm inclined to option 3. What do you think @GenericMappingTools/pygmt-maintainers?

Ok with this in principle, but I'm thinking of the variable names. How about:

• minimum_required_gmt_version="6.3.0" or minimum_supported_gmt_version="6.3.0"?
• recommended_gmt_version="6.4.0"?

References:

• https://en.wikipedia.org/wiki/System_requirements#Recommended_system_requirements
• Rust has a concept called Minimum Supported Rust Version (MSRV) for libraries/crates

Slightly off-topic, but I suppose we'll also set a requirement for gmt >=6.4.0,<7.0 on PyGMT's conda-forge package here at https://github.com/conda-forge/pygmt-feedstock/blob/e34ae5af8fced8600a9c05f5298c7e224e251530/recipe/meta.yaml#L25 for the PyGMT v0.14.0 release? So users would really need to install GMT 6.3.0 manually (not through conda) to get it to work with PyGMT v0.14.0?

[seisman]

• minimum_required_gmt_version="6.3.0" or minimum_supported_gmt_version="6.3.0"?

I prefer to minimum_required_gmt_version since GMT 6.3.0 is no longer officially supported.

• recommended_gmt_version="6.4.0"?

It reads like we recommend 6.4.0 and don't recommend 6.5.0. What about minimum_recommended_gmt_version?

Slightly off-topic, but I suppose we'll also set a requirement for gmt >=6.4.0,<7.0 on PyGMT's conda-forge package here at https://github.com/conda-forge/pygmt-feedstock/blob/e34ae5af8fced8600a9c05f5298c7e224e251530/recipe/meta.yaml#L25 for the PyGMT v0.14.0 release? So users would really need to install GMT 6.3.0 manually (not through conda) to get it to work with PyGMT v0.14.0?

Yes, I agree.

[seisman]

I think we have three options:

1. Bump required_gmt_version from 6.3.0 to 6.4.0, which means that people who use GMT 6.3 will see the GMTVersionError exception
2. Keep required_gmt_version="6.3.0" and add a note like "PyGMT requires GMT>=6.3.0 but only GMT 6.4-6.5 are fully tested" on the installation page.
3. Have two variables like required_gmt_version="6.4.0" and minimum_required_version="6.3.0", and raise the GMTVersionError for GMT<6.3.0 and raise an warning like "GMT 6.3.0 is not fully tested." for GMT=6.3.0.

After thinking twice, maybe we should go for option 1 for now to reduce our maintenance burden and revisit option 3 when we release PyGMT v1.0.

[weiji14]

In doc/install.md, change this line:

pygmt/doc/install.md

Line 311 in f8db417

- Ghostscript 9.53-9.56 for GMT 6.3.0/6.4.0

to "- Ghostscript 9.53-9.56 for GMT 6.4.0 (or below)"

[weiji14]

I'm getting a blank value with this as mentioned at #3468 (comment). Are you getting any output?

import pygmt

with pygmt.clib.Session() as lib:
    print(lib.info["image layout"])  # API_IMAGE_LAYOUT

output from lib.info dict:

{'version': '6.5.0',
 'padding': '2',
 'share dir': '~/mambaforge/envs/pygmt/share/gmt',
 'plugin dir': '~/mambaforge/envs/pygmt/lib/gmt/plugins',
 'library path': '~/mambaforge/envs/pygmt/lib/libgmt.so',
 'cores': '16',
 'grid layout': 'rows',
 'image layout': '',
 'binary version': '6.5.0'}