How to handel to leading "v" in the PyGMT release number? #4790
Description
Initial comments
- DOC/website: Move citiation information from README to separate file and subsection "citing" #4784 (comment)
- Changelog entry for v0.8.0 #2272 (comment)
Currently we use a leading "v" in the PyGMT release number. However, the sematic versioning concept does not support this, xref: https://semver.org/#is-v123-a-semantic-version.
For release 0.8.0, we decided to drop the "v" in the BibTeX entry in the README to be consistent with the CITIATION.cff file (https://github.com/GenericMappingTools/pygmt/pull/2272/changes#diff-7b3ed02bc73dc06b7db906cf97aa91dec2b2eb21f2d92bc5caa761df5bbc168f). But we still use it in the meta data for the Zenodo archive:
Thus, it is included in the cititation suggested by Zenodo, e.g., https://doi.org/10.5281/zenodo.3781524:
Tian, D., Leong, W. J., Fröhlich, Y., Grund, M., Schlitzer, W., Jones, M., Toney, L., Yao, J., Tong, J.-H., Magen, Y., Materna, K., Belem, A., Newton, T., Anant, A., Ziebarth, M., Quinn, J., He, X., Uieda, L.& Wessel, P. (2026). PyGMT: A Python interface for the Generic Mapping Tools (Version v0.19.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.19398871
Futuremore we use the "v" in the GitHub releases and tags and the file name for the Zenodo archive as well as in the table for the Minimum Supported Versions. It's also proposed in the Maintainers Guide.
We should think about whether we want to drop the "v" completely or, if not, where (and why) we still want to use it. Also need to update the Maintainers Guide afterward correspondently.
Handling by other projects
- GMT: Not used https://github.com/GenericMappingTools/gmt/releases, https://docs.generic-mapping-tools.org/6.7/changes.html
- NumPy: Used for GitHub tags https://github.com/GenericMappingTools/gmt/releases; not in docs https://numpy.org/doc/stable/
- pandas: Not used https://github.com/pandas-dev/pandas/releases, https://pandas.pydata.org/pandas-docs/stable/
Activity
seisman commentedon Aug 9, 2026
Just want to add some more background here.
In SemVer v1.0.0, it's clear that it recommended tagging a release with a leading
v(xref: https://semver.org/spec/v1.0.0.html#tagging-specification-semvertag). This tagging recommendation was later removed in SemVer v2.0.0 mainly because (semver/semver.org#1):GitHub also recommends a leading
vin tags (Click the "Draft a new release" button on the Release page, then you'll see the message on the right side):So, from what I understand,
0.19.0is the version number that follows SemVer, whilev0.19.0is the version string to refer to the software tag or release.Currently, the PyGMT version is used in the following places (feel free to make edits if you find more).
The "Correctness" column indicates whether the current version string follows the strict definition mentioned above. ✅ means correct; ❌ means incorrect; ❓ means unsure or doens't matter.
v0.19.0v2.5.2; pandas:v3.0.5; xarray:v2026.07.0v0.19.03.0.5, numpy:v2.5.1 (July 4, 2026), xaray:v2026.07.0v0.19.02.1, numpy:2.5, xarray:v2026.07.0pygmt.__version__v0.19.0orv0.19.0.dev5+gabcdef2.1.0, numpy:2.5.1, xarray:2026.7.0v0.19.0v?versionfield inCITATION.cff0.19.0versionfiled indoc/citing.md0.19.0v0.19.0vto be more consistent with version string of other packages?Release v0.19.0NumPy 2.5.0 Release Notes; pandas:Version 3.0; xarray:v2026.07.0 (Jul 9, 2026)pygmt.egg-info/scm_version.json'stagfield0.19.00.19.00.19.00.20.0.dev600.19.0versionfield on Zenodov0.19.0Based on the above observations, I suggest:
0.19.0inpygmt.__version__Follow Semantic Versioning and remove the leading v from version string #48380.19.0in deprecation messages Follow Semantic Versioning and remove the leading v from version string #4838UseCan't update it, as explained in Follow Semantic Versioning and remove the leading v from version string #4838 (comment).0.19.0in "Minimum Supported Version" [Because the column title is "PyGMT version"]0.19.0in Zenodoversionfieldseisman commentedon Aug 13, 2026
Ping @GenericMappingTools/pygmt-maintainers for comments on the proposed changes.
weiji14 commentedon Aug 13, 2026
Ok for these ones. I checked a few other libraries (numpy, pandas, xarray, rioxarray) and their
__version__method doesn't return thevprefix.Ok for this too, I see at https://blog.zenodo.org/2017/11/02/version-field/ that they "strongly suggest that [you] use semantic versioning for machine-readability" as @yvonnefroehlich mentioned above. But do we keep the
vin the zip file name? Also, do we want to backport thevprefix removal for old Zenodo versions, or just v0.20.0 going forward?seisman commentedon Aug 14, 2026
The ZIP file downloaded from GitHub Released has a file name like
pygmt-0.19.0.zip, and we renamed it topygmt-v0.19.0.zipmanually before uploading to Zenodo. I think we should not addvto the ZIP file.I'm OK with either. It would good to fix all records.
seisman commentedon Aug 14, 2026
Better to work on this issue after #4824.
seisman commentedon Aug 22, 2026
I've uploaded the
versionfield for all Zenodo records. Closing.yvonnefroehlich commentedon Aug 22, 2026
Should we also update the titles of the ResearchGate uploads and maybe of the announcements on the GMT forum.
seisman commentedon Aug 22, 2026
I don't think it's worth the time
yvonnefroehlich commentedon Aug 24, 2026
It's probably not (easy) possible to change the text shown on the badges:
Also the GMT repo has the leading "v" in the badges text: