Xarray versioning to switch to CalVer

[jhamman]

Xarray is planning to switch to Calendar versioning (calver). This issue serves as a general announcement.

The idea has come up in multiple developer meetings (#4001) and is part of a larger effort to increase our release cadence (#5927). Today's developer meeting included unanimous consent for the change. Other projects in Xarray's ecosystem have also made this change recently (e.g. dask/community#100). While it is likely we will make this change in the next release or two, users and developers should feel free to voice objections here.

The proposed calver implementation follows the same schema as the Dask project, that is; YYYY.MM.X (4 digit year, two digit month, one digit micro zero-indexed version. For example, the code block below provides comparison of the current and future version tags:

In [1]: import xarray as xr

# current
In [2]: xr.__version__
Out[2]: '0.19.1'

# proposed
In [2]: xr.__version__
Out[2]: '2022.01.0'

cc @pydata/xarray

[ksunden]

Note that PEP 440 normalizes integers in version strings, so leading zeros are ignored and the version as it appears in PyPI would be 2022.1.0, as that displays the normalized version string.

On my own packages which I use calver for I have opted to not have leading zeros such that the "canonical" version matches the "normalized" version to avoid any confusion that may cause.

[jhamman]

Interesting insights @ksunden, thanks for sharing!

Do others have thoughts here? I would support stripping the leading zeros from the MM part of the version string in favor of consistency here.

[andersy005]

Do others have thoughts here? I would support stripping the leading zeros from the MM part of the version string in favor of consistency here.

I'm in favor of a non-zero-padded version for the benefit of having canonical/normalized versions that also match git tags/history

[Illviljan]

Note that PEP 440 normalizes integers in version strings, so leading zeros are ignored and the version as it appears in PyPI would be 2022.1.0, as that displays the normalized version string.

On my own packages which I use calver for I have opted to not have leading zeros such that the "canonical" version matches the "normalized" version to avoid any confusion that may cause.

No opinion either way here but 2022.01.0 is an easier string to sort.

@jrbourbeau is this something dask has thought about?

[keewis]

note that PEP440 itself is not really consistent: it mentions both normal and zero-padded CalVer.

Also, in the issue in which dask discussed this, one of the people involved with the PyPA stated that the difference between omitting or keeping the zero-padding is purely aesthetic (both can be parsed using packaging.version.Version / packaging.version.parse). I assume that means we're free to choose? The YYYY.MM.X scheme seems to be fairly common now, though.

Edit: I would vote for zero-padding of the months because that will make it actually recognizable as a date.

[ksunden]

setup.py sdist bdist_wheel creates files in dist/ that have the leading zeros removed.

I did git tag v2022.01.0 and then built the wheel/sdist and got: xarray-2022.1.0-py3-none-any.whl and xarray-2022.1.0.tar.gz and xarray.__version__ gave 2022.1.0

I do understand the appeal of leading zeros, I started off using them myself, but pypi/setuptools/etc will bring in inconsistencies that you will either need to fight against or give into the consistent way, which is sans leading zero (that is the path I chose)

[jrbourbeau]

@jrbourbeau is this something dask has thought about?

Thanks for the ping @Illviljan. Zero-padding dates did come up in the Dask calver discussion starting here dask/community#100 (comment). In a nutshell, there was a slight preference towards using zero-padding (i.e. 2022.01.0 instead of 2022.1.0) because the calendar nature of the version is more explicit and string sorting and full-fledged package sorting (like one would do with packaging.version) give the same result.

As pointed out dask/community#100 (comment) either convention is valid from a Python packaging perspective. FWIW I'm not aware of any issues that have come up from Dask using a zero-padded version number. The main thing that comes to mind is when checking out git tags for a specific release (e.g. git checkout 2021.04.0 and git checkout 2021.4.0 are not equivalent). That said, to my knowledge, this hasn't been an issue in practice.

EDIT: To be clear, I'm not advocating for one convention over the other -- just providing context around Dask's decision

[jhamman]

After thinking on this one a bit, I'm back to thinking we should zero-pad the months. I don't think there is a clear right choice here, with both options offering pros/cons. Thanks @ksunden in particular for sharing your perspective). I suggest we try this in 2022.02.0. See #6214 for more details.

[brews]

Using semver can be handy to signal breaking changes. Any thoughts on how xarray will handle breaking changes with calver? Any release can break, or during select periods, after a timeout, etc.?

[shoyer]

Breaking changes will continue to be very rare, and whenever possible will be preceeded by deprecation or future warnings for multiple months.