Backwards compatibility and deprecation policy

[seisman]

As stated in many places, PyGMT is still not a finished project:

All of the API (functions/classes/interfaces) is subject to change until we reach v1.0.0 as per the semantic versioning specification. There may be non-backward compatible changes as we experiment with new design ideas and implement new features.

So we're allowed to break backward-compatibility in any major and minor versions. However, from users' point of view, they would be disappointed when they find that their scripts break after upgrading PyGMT. There are always be some trade-offs between users' and developers' experiences.

We now already have some open issues that might break backward-compatibility, e.g.,

• Rename the sizes parameter in plot/plot3d to be size #1118
• Incorrect parameter in Figure.meca() #1094
• Consistent (non-common) aliases between modules #1042
• Remove the xshift (X) and yshift (Y) aliases from all plotting modules? #924
• Disallow single character arguments #262
• Arguments with spaces in strings #247
• Better return values for grdinfo #593

It's time for us to discuss about how we will handle backward compatibility and how to deprecate/remove existing features.

Resources:

• https://www.python.org/dev/peps/pep-0387/
• https://numpy.org/neps/nep-0023-backwards-compatibility.html

[michaelgrund]

I'm definitely a fan of backwards compatibility, however, if some points are changed to improve the overall product one has to think about how this should be handled. For example, when I started using PyGMT in 2019 several aliases were not implemented but now they are. Of course we support both, original GMT shortcuts and aliases and thus my notebooks will still work, however, some other things like how data is passed into a module slightly changed and there might appear issues.

Therefore, as @seisman mentioned, supporting backwards compatibility is (in my opinion) necessary, especially to avoid disappointed early stage users which potentially have not the time to adjust their scripts every few months. I think a good balance between useful improvements and some kind of backwards compatibility would be a good choice (no idea how to handle that 😄).

[seisman]

IMHO, we should try our best to:

1. Keep backward-compatibility
2. Raise deprecation warnings if users are using the old syntax
3. Fully deprecate old syntax or remove unsupported features after X minor versions or X months.

[seisman]

IMHO, we should try our best to:

1. Keep backward-compatibility
2. Raise deprecation warnings if users are using the old syntax
3. Fully deprecate old syntax or remove unsupported features after X minor versions or X months.

Ping @GenericMappingTools/pygmt-contributors for thoughts.

[maxrjones]

IMHO, we should try our best to:

1. Keep backward-compatibility
2. Raise deprecation warnings if users are using the old syntax
3. Fully deprecate old syntax or remove unsupported features after X minor versions or X months.

Ping @GenericMappingTools/pygmt-contributors for thoughts.

I agree. I think we talked about quarterly releases at the last community meeting, so I think 4 minor versions or 12 months would be a good guideline for full deprecation.

[weiji14]

IMHO, we should try our best to:

1. Keep backward-compatibility
2. Raise deprecation warnings if users are using the old syntax
3. Fully deprecate old syntax or remove unsupported features after X minor versions or X months.

Ping @GenericMappingTools/pygmt-contributors for thoughts.

I agree. I think we talked about quarterly releases at the last community meeting, so I think 4 minor versions or 12 months would be a good guideline for full deprecation.

Since we're at v0.x.y, I think 1 or 2 minor versions should be enough (3-6 months). NumPy has some good notes at NEP23 https://numpy.org/neps/nep-0023-backwards-compatibility.html on how to handle deprecation, but I think we can apply a simpler/shorter deprecation cycle for the alias name changes. More complex changes could span 3-4 minor versions as Meghan noted.

[seisman]

I prefer at least 2 minor versions, just in case that people install v0.4.0 and we release v0.5.0 next day 😄

[willschlitzer]

I think a way we can negate some of the problems with breaking backwards compatibility is to make it prominent in our release notes what breaking changes are included, and maybe include a page in the documentation that lists what "broke" in between different releases, as well as clear instructions on how to install old versions if necessary.

I'm sure there will still be people unhappy with breaking changes, but I think this at least gives someone a tutorial on how to make their scripts works when they're hurriedly trying to finish their thesis and they updated PyGMT without realizing what would break.

[seisman]

to make it prominent in our release notes what breaking changes are included,

Yes, breaking changes will be included in the release notes. When we deprecate a feature but keep backwards compatibility, the changes will be in the "Deprecation" section. When we fully remove a feature, the changes will be highlighted in the "Breaking changes" section.

and maybe include a page in the documentation that lists what "broke" in between different releases, as well as clear instructions on how to install old versions if necessary.

Since breaking changes are documented in the release notes, I feel it's unnecessary to have another page listing "breaking changes".

I'm sure there will still be people unhappy with breaking changes, but I think this at least gives someone a tutorial on how to make their scripts works when they're hurriedly trying to finish their thesis and they updated PyGMT without realizing what would break.

Currently, most of the breaking changes are renaming function parameters, so the warning message should be enough to help the script migration. For more complicated breaking changes, a detailed tutorial sounds like a good idea.

See #1160 for a draft deprecation policy and comments are welcomed.

[weiji14]

So can we get a consensus on the number of minor versions to raise the FutureWarning for? Let's vote @GenericMappingTools/pygmt-team (specifically for long the FutureWarning should show up for alias name changes):

🎉 4 minor versions as per #1120 (comment)
👀 2 minor versions as per #1120 (comment)
🚀 0 minor versions as per #1120 (comment)

Rules: You may vote for more than one option. Voting time ends on Thursday 15 Apr 2021 (midnight UTC time).

[maxrjones]

So can we get a consensus on the number of minor versions to raise the FutureWarning for? Let's vote (specifically for the alias name change case):

🎉 3-4 minor versions as per #1120 (comment)
👀 1-2 minor versions as per #1120 (comment)
🚀 0 minor versions as per #1120 (comment)

Rules: You may vote for more than one option. Voting time ends on Thursday 15 Apr 2021 (midnight UTC time).

I prefer 2 minor releases for alias updates, but not 1. Sorry to break your poll. My reasoning here is that it usually takes longer than 3 months to get a paper back, so I could imagine someone easily missing a minor release if they have moved on to teaching or some other tasks and then scrambling to update their broken aliases.

[weiji14]

Ok, will make it more clear-cut then. Updated to be 0, 2 and 4 only.

[seisman]

Are we voting for alias name changes or any incompatible changes? 2 minor releases is enough for alias changes, but for other changes (I/O changes), 4 releases is better.

[core-man]

Are we voting for alias name changes or any incompatible changes? 2 minor releases is enough for alias changes, but for other changes (I/O changes), 4 releases is better.

I agree. The alias name is easy to be revised in our scripts, but the I/O changes may not.

[seisman]

I think we all agree that we should raise the FutureWarning for at least two minor versions. Please give #1160 a final review, so that we can merge the @deprecate_parameter decorator and change some parameter names in #1118, #1042.

[seisman]

Closed by #1160.