Follow Semantic Versioning and remove the leading v from version string by seisman · Pull Request #4838 · GenericMappingTools/pygmt

seisman · 2026-08-14T10:03:58Z

Previously, pygmt.__version__ was in the format of vX.Y.Z. This PR removes the leading v, thus, the version is in the format of X.Y.Z.

It should has minor effects on users, as packaging.version.Version can handle leading v properly:

>>> from packaging.version import Version
>>> Version("0.19.0") == Version("v0.19.0")
True

Addresses #4790

I used ack 'v[0-9]*\.[0-9]*\.[0-9]*' to ensure are related cases are fixed, except:

doc/_static/version_switch.js: 'v0.19.0': 'v0.19.0'. The first one controls the URL, while the 2nd one controls the text string shown in the version switcher. We can't update the first one, because it will break many existing references to the PyGMT documentation. I think it's better to keep these two consistent. So, none of them are changed.
doc/minversions.md: The first column shows v0.19.0. It's technically difficult to change it to 0.19.0, because it's linked to the v0.19.0 tag.

Preview: https://pygmt-dev--4838.org.readthedocs.build/en/4838/index.html

Copilot

Pull request overview

This PR updates PyGMT to follow Semantic Versioning more strictly by removing the leading v from pygmt.__version__, and aligns various deprecation markers, warnings, comments, and maintenance documentation with the X.Y.Z version format.

Changes:

Change pygmt.__version__ to return X.Y.Z (no leading v) via importlib.metadata.version.
Update deprecation directives/decorator arguments and warning/error message text to use X.Y.Z.
Adjust maintainer/release documentation and checklist to reflect the new version-string convention.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`pygmt/_show_versions.py`	Removes `v` prefix from `__version__` and updates Ghostscript/GMT warning strings.
`pygmt/helpers/decorators.py`	Updates version strings in comments/errors and in `deprecate_parameter` doc examples.
`pygmt/src/basemap.py`	Updates deprecation notes and warning message to use `0.19.0` format.
`pygmt/src/coast.py`	Updates deprecation directive version formatting and reflows text.
`pygmt/src/subplot.py`	Updates deprecated directive and `deprecate_parameter` decorator version args.
`pygmt/src/grdsample.py`	Updates `deprecate_parameter` decorator version args.
`pygmt/clib/session.py`	Updates version references in comments to drop leading `v`.
`pygmt/figure.py`	Updates a comment that references a dependency version string.
`pygmt/datasets/tile_map.py`	Minor comment tweak; still uses `pygmt.__version__` for User-Agent construction.
`pygmt/tests/test_timestamp.py`	Updates docstring text referencing the removal version.
`doc/maintenance.md`	Updates semantic-versioning wording and deprecation example versions.
`.github/ISSUE_TEMPLATE/4-release_checklist.md`	Updates release checklist guidance for version strings (including Zenodo `version` field).

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

seisman · 2026-08-14T11:22:54Z

    # TODO(contextily>=1.7.0): Remove once contextily>=1.7.0 is required.
-    # The 'headers' parameter was added in contextily v1.7.0
+    # The 'headers' parameter was added in contextily 1.7.0.
    if Version(contextily.__version__) < Version("1.7.0"):


Fixed in 02dd66b.

seisman · 2026-08-14T11:24:35Z

 # Get semantic version through setuptools-scm
-__version__ = f"v{version('pygmt')}"  # e.g. v0.1.2.dev3+g0ab3cd78
+__version__ = version("pygmt")  # e.g., 0.1.2.dev3+g0ab3cd78
 __commit__ = (  # 0ab3cd78
    __version__.rsplit(sep="+g", maxsplit=1)[-1] if "+g" in __version__ else ""
 )


Fixed in 8cf07e4.

yvonnefroehlich

Wondering if we should update the table for the Minimum Supported Version (https://pygmt-dev--4838.org.readthedocs.build/en/4838/minversions.html), even we are linking to the GitHub tags, where we still use the "v".

Edit: See first comment of PR why this was not changed.

yvonnefroehlich

Do the changes in this PR affect the URL to the PyGMT website? Currently we use the "v" there, e.g., https://www.pygmt.org/v0.19.0/index.html. If we remove the "v", the old version specific URLs will not resolve anymore.

Edit: Not changed, see first comment of this PR.

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

seisman · 2026-08-21T17:35:04Z

Wondering if we should update the table for the Minimum Supported Version (https://pygmt-dev--4838.org.readthedocs.build/en/4838/minversions.html), even we are linking to the GitHub tags, where we still use the "v".

Edit: See first comment of PR why this was not changed.

It's not that difficult as I initially thought. See changes in 52d49f7.

Edit: Actually, changes in 52d49f7 works well for <tag:0.19.0>/<doc:0.19.0> but not for <doc:dev>/doc:dev/pygmt-docs.zip, so I have to revert that commit.

This reverts commit 52d49f7.

Copilot

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

seisman added 4 commits August 14, 2026 18:06

Remove leading v from pygmt.__version__

7040f6d

Remove leading v in decorator deprecate_parameter

4ce2b02

Remove leading v from deprecation messages and comments

03e8bc8

Fix remaining cases

010f7e5

seisman force-pushed the semver branch from a6aef0d to 010f7e5 Compare August 14, 2026 10:07

seisman added maintenance Boring but important stuff for the core devs needs review This PR has higher priority and needs review. labels Aug 14, 2026

seisman added this to the 0.20.0 milestone Aug 14, 2026

seisman mentioned this pull request Aug 14, 2026

How to handel to leading "v" in the PyGMT release number? #4790

Open

Add a note in release checklist

a98db0c

seisman requested a lite review from Copilot August 14, 2026 11:06

Copilot started reviewing on behalf of seisman August 14, 2026 11:06 View session

Copilot AI reviewed Aug 14, 2026

View reviewed changes

seisman added 4 commits August 14, 2026 19:20

Fix the version string in User-Agent passed to contextily

02dd66b

Manually add the leading v for tags in doc/conf.py

8cf07e4

Merge branch 'main' into semver

ef3ade3

Merge branch 'main' into semver

99dffad

seisman added final review call This PR requires final review and approval from a second reviewer and removed needs review This PR has higher priority and needs review. labels Aug 21, 2026

seisman requested a review from a team August 21, 2026 08:24

Merge branch 'main' into semver

ec40590

yvonnefroehlich reviewed Aug 21, 2026

View reviewed changes

Comment thread pygmt/helpers/decorators.py Outdated

Comment thread pygmt/helpers/decorators.py Outdated

Comment thread pygmt/helpers/decorators.py Outdated

yvonnefroehlich reviewed Aug 21, 2026

View reviewed changes

seisman and others added 2 commits August 22, 2026 01:25

Improve error for deprecated parameters

c486cb9

Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>

Display version string without v in minversions.md

52d49f7

seisman added 2 commits August 22, 2026 01:35

Merge branch 'main' into semver

4012c0b

Revert "Display version string without v in minversions.md"

e392970

This reverts commit 52d49f7.

seisman requested a lite review from Copilot August 22, 2026 03:52

Copilot started reviewing on behalf of seisman August 22, 2026 03:53 View session

Copilot AI reviewed Aug 22, 2026

View reviewed changes

Navigation Menu

Uh oh!

Follow Semantic Versioning and remove the leading v from version string - #4838

Follow Semantic Versioning and remove the leading v from version string#4838
seisman wants to merge 14 commits into
mainfrom
semver

seisman commented Aug 14, 2026 •

edited by yvonnefroehlich

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

seisman Aug 14, 2026

Uh oh!

seisman Aug 14, 2026

Uh oh!

yvonnefroehlich left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yvonnefroehlich left a comment •

edited

Loading

Uh oh!

seisman commented Aug 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

seisman commented Aug 14, 2026 • edited by yvonnefroehlich Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

seisman Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

seisman Aug 14, 2026

Choose a reason for hiding this comment

Uh oh!

yvonnefroehlich left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yvonnefroehlich left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

seisman commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

seisman commented Aug 14, 2026 •

edited by yvonnefroehlich

Loading

yvonnefroehlich left a comment •

edited

Loading

yvonnefroehlich left a comment •

edited

Loading

seisman commented Aug 21, 2026 •

edited

Loading