Assigning updates to major and minor releases

[willschlitzer]

As I understand the versioning system, a minor release will cover relatively minor changes (documentation updates and bug fixes are the examples that come to mind), while major changes, primarily new modules being wrapped, will be covered in the major releases. How do we control which release a given pull request/merge applies to? I'm assuming we'll release a v0.3.1 sometime in the next few months that will cover minor fixes and updates, but pull requests that add functions like rose and solar will be included in v0.4.0 sometime after v0.3.1 (or v0.3.2). Since there is just one master branch, how do we control what will be included on a given release, and how do we withhold major updates from minor releases?

[weiji14]

Excellent question. We discussed this a while ago, see #424 (comment) and also #665 (comment). If any new modules get into the master branch, then we release v0.4.0, else we just do a v0.3.1. The advanced branching strategy with backports and stuff was trialed in upstream GMT for a while during GMT 6.1.1 and was a bit of a chore. Probably don't need it until PyGMT reaches v1, but happy to revisit this topic

[willschlitzer]

@weiji14 That makes sense for how to determine if it's major or minor release. I think PyGMT is small enough that these releases won't have much in the way of breaking changes (we hope) to necessitate someone using a patched older release. Thanks for clearing this up, I didn't want to merge any PRs that have major changes only to find out I should have waited until after v0.3.1 is released.

[seisman]

As I understand the versioning system, a minor release will cover relatively minor changes (documentation updates and bug fixes are the examples that come to mind), while major changes, primarily new modules being wrapped, will be covered in the major releases.

Just to make it clear, the version number is major.minor.patch, so:

• a patch release will cover relatively small changes (documentation updates and bug fixes are the examples that come to mind)
• a minor release will cover new features (new modules being wrapped, new parameters)

[seisman]

Can we close this? Or is there anything we need to add to the MAINTENANCE.md?

[weiji14]

Might be good to bring up your comment at #941 (comment) here:

It seems that recent release-drafter releases have more features, for example version-resolver probably can determine if the next version is v0.3.1 or v0.4.0.

If I understand it correctly, the following setting means that if any PR labeled with "feature" or "enhancement" is merged into master branch, the next version will be a minor release (i.e., v0.4.0), otherwise it's a patch release (i.e., v0.3.1). However, sometimes we merge PRs with "enhancement" but may don't want to bump the minor version (e.g., #952).

version-resolver:
  minor:
    labels:
      - 'feature'
      - 'enhancement'
  default: patch

I can add it to the PR at #907 which is updating the 'Releasing' section in MAINTENANCE.md

[seisman]

Sounds good. Then I need to remove the "enhancement" label from PR #952, and maybe declare it as a bug.

[weiji14]

So semver v2.0.0 at https://semver.org/spec/v2.0.0.html says:

Given a version number MAJOR.MINOR.PATCH, increment the:

2. MINOR version when you add functionality in a backwards compatible manner, and
3. PATCH version when you make backwards compatible bug fixes.

Is an 'enhancement' always considered a new functionality? I'm thinking whether we could just bump the minor version if there is a 'feature' added? I.e. have just:

version-resolver:
  minor:
    labels:
      - 'feature'
  default: patch

but not quite sure if my interpretation of semver here is correct.

[seisman]

I think it's pretty subjective. Looking at the previous changelogs, most of the "enhancements" are adding new aliases to existing modules, or allowing more data types as input or output. They can all be declared as bugs 😄