adopt setuptools-scm for auto versioning (SciTools#4841)

* adopt setuptools-scm for auto versioning

* update py310.yml requirements

* update locks

* simplify docs version

* update dev release docs

* update .gitignore for vscode

* update locks

* add exclude _version.py to MANIFEST.in

* review actions

* update lock files

* update pyproject.toml

* what a whatsnew entry

.git_archival.txt

@@ -0,0 +1,4 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true)$
+ref-names: $Format:%D$

.gitattributes

@@ -0,0 +1 @@
+.git_archival.txt  export-subst

.gitignore

@@ -1,5 +1,8 @@
 *.py[co]
 
+# setuptools-scm
+_version.py
+
 # Environment file which should be autogenerated
 *conda_requirements.txt*
 
@@ -55,6 +58,9 @@ lib/iris/tests/results/imagerepo.lock
 /.idea
 *.cover
 
+# vscode files
+.vscode
+
 # Auto generated documentation files
 docs/src/_build/*
 docs/src/generated

MANIFEST.in

@@ -21,3 +21,4 @@ include etc/cf-standard-name-table.xml
 global-exclude *.pyc
 global-exclude __pycache__
 global-exclude iris_image_test_output
+exclude lib/iris/_version.py

docs/src/conf.py

@@ -20,15 +20,14 @@
 # ----------------------------------------------------------------------------
 
 import datetime
+from importlib.metadata import version as get_version
 import ntpath
 import os
 from pathlib import Path
 import re
 import sys
 import warnings
 
-import iris
-
 
 # function to write  useful output to stdout, prefixing the source.
 def autolog(message):
@@ -85,21 +84,10 @@ def autolog(message):
 author = "Iris Developers"
 
 # The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-
-# The short X.Y version.
-if iris.__version__ == "dev":
-    version = "dev"
-else:
-    # major.minor.patch-dev -> major.minor.patch
-    version = ".".join(iris.__version__.split("-")[0].split(".")[:3])
-
-# The full version, including alpha/beta/rc tags.
-release = iris.__version__
+# |version|, also used in various other places throughout the built documents.
 
-autolog("Iris Version = {}".format(version))
-autolog("Iris Release = {}".format(release))
+version = get_version("scitools-iris")
+autolog(f"Iris Version = {version}")
 
 # -- General configuration ---------------------------------------------------
 

docs/src/developers_guide/release.rst

@@ -100,12 +100,14 @@ Steps to achieve this can be found in the :ref:`iris_development_releases_steps`
 The Release
 -----------
 
-The final steps of the release are to change the version string ``__version__``
-in the source of :literal:`iris.__init__.py` and ensure the release date and details
+The final steps of the release are to ensure that the release date and details
 are correct in the relevant ``whatsnew`` page within the documentation.
 
-Once all checks are complete, the release is cut by the creation of a new tag
-in the ``SciTools/iris`` repository.
+There is no need to update the ``iris.__version__``, as this is managed
+automatically by `setuptools-scm`_.
+
+Once all checks are complete, the release is published on GitHub by
+creating a new tag in the ``SciTools/iris`` repository.
 
 
 Update conda-forge
@@ -179,14 +181,14 @@ For further details on how to test Iris, see :ref:`developer_running_tests`.
 Merge Back
 ----------
 
-After the release is cut, the changes from the release branch should be merged
+After the release is published, the changes from the release branch should be merged
 back onto the ``SciTools/iris`` ``main`` branch.
 
 To achieve this, first cut a local branch from the latest ``main`` branch,
 and `git merge` the :literal:`.x` release branch into it. Ensure that the
-``iris.__version__``, ``docs/src/whatsnew/index.rst``,
-and ``docs/src/whatsnew/latest.rst`` are correct, before committing these changes
-and then proposing a pull-request on the ``main`` branch of ``SciTools/iris``.
+``docs/src/whatsnew/index.rst`` and ``docs/src/whatsnew/latest.rst`` are
+correct, before committing these changes and then proposing a pull-request
+on the ``main`` branch of ``SciTools/iris``.
 
 
 Point Releases
@@ -274,4 +276,5 @@ Post Release Steps
 .. _rc_iris: https://anaconda.org/conda-forge/iris/labels
 .. _Generating Distribution Archives: https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives
 .. _Packaging Your Project: https://packaging.python.org/guides/distributing-packages-using-setuptools/#packaging-your-project
-.. _latest CF standard names: http://cfconventions.org/standard-names.html
+.. _latest CF standard names: http://cfconventions.org/standard-names.html
+.. _setuptools-scm: /~https://github.com/pypa/setuptools_scm

docs/src/whatsnew/latest.rst

@@ -251,6 +251,9 @@ This document explains the changes made to Iris for this release
    the GitHub Continuous-Integration to cover testing on ``py38``, ``py39``,
    and ``py310``. (:pull:`4840` and :pull:`4852`)
 
+#. `@bjlittle`_ and `@trexfeathers`_ (reviewer) adopted `setuptools-scm`_ for
+   automated ``iris`` package versioning. (:pull:`4841`)
+
 
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,
@@ -265,3 +268,4 @@ This document explains the changes made to Iris for this release
 .. _Calendar: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#calendar
 .. _Cell Boundaries: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.9/cf-conventions.html#cell-boundaries
 .. _PyData Sphinx Theme: https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html
+.. _setuptools-scm: /~https://github.com/pypa/setuptools_scm

lib/iris/__init__.py

@@ -97,19 +97,18 @@ def callback(cube, field, filename):
 import threading
 
 import iris._constraints
-from iris._deprecation import IrisDeprecation, warn_deprecated
 import iris.config
 import iris.io
 
+from ._deprecation import IrisDeprecation, warn_deprecated
+from ._version import version as __version__  # noqa: F401
+
 try:
     import iris_sample_data
 except ImportError:
     iris_sample_data = None
 
 
-# Iris revision.
-__version__ = "3.3.dev0"
-
 # Restrict the names imported when using "from iris import *"
 __all__ = [
     "AttributeConstraint",

pyproject.toml

@@ -1,12 +1,16 @@
 [build-system]
 # Defined by PEP 518
 requires = [
-  "setuptools>=40.8.0",
+  "setuptools>=45",
+  "setuptools_scm[toml]>=7.0",
   "wheel",
 ]
 # Defined by PEP 517
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools_scm]
+write_to = "lib/iris/_version.py"
+local_scheme = "dirty-tag"
 
 [tool.black]
 line-length = 79

requirements/ci/nox.lock/py310-linux-64.lock

@@ -1,6 +1,6 @@
 # Generated by conda-lock.
 # platform: linux-64
-# input_hash: 067d55c87f97649f3822a424e6b2d4b8d6a5995536c8f513e02f1d31400bcf72
+# input_hash: b9e611fba7bc4bd71c8f4e36acf1dde0bd10352159237ea4d2e979ee66214d23
 @EXPLICIT
 https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2#d7c89558ba9fa0495403155b64376d81
 https://conda.anaconda.org/conda-forge/linux-64/ca-certificates-2022.6.15-ha878542_0.tar.bz2#c320890f77fd1d617fa876e0982002c2
@@ -26,7 +26,7 @@ https://conda.anaconda.org/conda-forge/linux-64/c-ares-1.18.1-h7f98852_0.tar.bz2
 https://conda.anaconda.org/conda-forge/linux-64/expat-2.4.8-h27087fc_0.tar.bz2#e1b07832504eeba765d648389cc387a9
 https://conda.anaconda.org/conda-forge/linux-64/fftw-3.3.10-nompi_h77c792f_102.tar.bz2#208f18b1d596b50c6a92a12b30ebe31f
 https://conda.anaconda.org/conda-forge/linux-64/fribidi-1.0.10-h36c2ea0_0.tar.bz2#ac7bc6a654f8f41b352b38f4051135f8
-https://conda.anaconda.org/conda-forge/linux-64/geos-3.10.3-h27087fc_0.tar.bz2#d11cf000ee8b976b5ce3b425477b5689
+https://conda.anaconda.org/conda-forge/linux-64/geos-3.11.0-h27087fc_0.tar.bz2#a583d0bc9a85c48e8b07a588d1ac8a80
 https://conda.anaconda.org/conda-forge/linux-64/giflib-5.2.1-h36c2ea0_2.tar.bz2#626e68ae9cc5912d6adb79d318cf962d
 https://conda.anaconda.org/conda-forge/linux-64/graphite2-1.3.13-h58526e2_1001.tar.bz2#8c54672728e8ec6aa6db90cf2806d220
 https://conda.anaconda.org/conda-forge/linux-64/icu-70.1-h27087fc_0.tar.bz2#87473a15119779e021c314249d4b4aed
@@ -97,7 +97,7 @@ https://conda.anaconda.org/conda-forge/linux-64/libnghttp2-1.47.0-h727a467_0.tar
 https://conda.anaconda.org/conda-forge/linux-64/libpng-1.6.37-h21135ba_2.tar.bz2#b6acf807307d033d4b7e758b4f44b036
 https://conda.anaconda.org/conda-forge/linux-64/libssh2-1.10.0-ha56f1ee_2.tar.bz2#6ab4eaa11ff01801cffca0a27489dc04
 https://conda.anaconda.org/conda-forge/linux-64/libtiff-4.4.0-hc85c160_1.tar.bz2#151f9fae3ab50f039c8735e47770aa2d
-https://conda.anaconda.org/conda-forge/linux-64/libxml2-2.9.14-h22db469_0.tar.bz2#7d623237b73d93dd856b5dd0f5fedd6b
+https://conda.anaconda.org/conda-forge/linux-64/libxml2-2.9.14-h22db469_3.tar.bz2#b6f4a0850ba620030a48b88c25497aaa
 https://conda.anaconda.org/conda-forge/linux-64/libzip-1.9.2-hc869a4a_0.tar.bz2#2d9e11c1183391882e95fec81d0d71c8
 https://conda.anaconda.org/conda-forge/linux-64/mysql-libs-8.0.29-h28c427c_1.tar.bz2#36dbdbf505b131c7e79a3857f3537185
 https://conda.anaconda.org/conda-forge/linux-64/sqlite-3.39.0-h4ff8645_0.tar.bz2#ead30581ba8cfd52d69632868b844d4a
@@ -143,7 +143,7 @@ https://conda.anaconda.org/conda-forge/noarch/fsspec-2022.5.0-pyhd8ed1ab_0.tar.b
 https://conda.anaconda.org/conda-forge/linux-64/glib-2.70.2-h780b84a_4.tar.bz2#977c857d773389a51442ad3a716c0480
 https://conda.anaconda.org/conda-forge/linux-64/hdf5-1.12.1-mpi_mpich_h08b82f9_4.tar.bz2#975d5635b158c1b3c5c795f9d0a430a1
 https://conda.anaconda.org/conda-forge/noarch/idna-3.3-pyhd8ed1ab_0.tar.bz2#40b50b8b030f5f2f22085c062ed013dd
-https://conda.anaconda.org/conda-forge/noarch/imagesize-1.3.0-pyhd8ed1ab_0.tar.bz2#be807e7606fff9436e5e700f6bffb7c6
+https://conda.anaconda.org/conda-forge/noarch/imagesize-1.4.1-pyhd8ed1ab_0.tar.bz2#7de5386c8fea29e76b303f37dde4c352
 https://conda.anaconda.org/conda-forge/noarch/iniconfig-1.1.1-pyh9f0ad1d_0.tar.bz2#39161f81cc5e5ca45b8226fbb06c6905
 https://conda.anaconda.org/conda-forge/noarch/iris-sample-data-2.4.0-pyhd8ed1ab_0.tar.bz2#18ee9c07cf945a33f92caf1ee3d23ad9
 https://conda.anaconda.org/conda-forge/linux-64/jack-1.9.18-h8c3723f_1002.tar.bz2#7b3f287fcb7683f67b3d953b79f412ea
@@ -169,14 +169,15 @@ https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-serializinghtml-1.1.
 https://conda.anaconda.org/conda-forge/noarch/toml-0.10.2-pyhd8ed1ab_0.tar.bz2#f832c45a477c78bebd107098db465095
 https://conda.anaconda.org/conda-forge/noarch/tomli-2.0.1-pyhd8ed1ab_0.tar.bz2#5844808ffab9ebdb694585b50ba02a96
 https://conda.anaconda.org/conda-forge/noarch/toolz-0.11.2-pyhd8ed1ab_0.tar.bz2#f348d1590550371edfac5ed3c1d44f7e
+https://conda.anaconda.org/conda-forge/noarch/typing_extensions-4.3.0-pyha770c72_0.tar.bz2#a9d85960bc62d53cc4ea0d1d27f73c98
 https://conda.anaconda.org/conda-forge/noarch/wheel-0.37.1-pyhd8ed1ab_0.tar.bz2#1ca02aaf78d9c70d9a81a3bed5752022
 https://conda.anaconda.org/conda-forge/noarch/zipp-3.8.0-pyhd8ed1ab_0.tar.bz2#050b94cf4a8c760656e51d2d44e4632c
 https://conda.anaconda.org/conda-forge/linux-64/antlr-python-runtime-4.7.2-py310hff52083_1003.tar.bz2#8324f8fff866055d4b32eb25e091fe31
 https://conda.anaconda.org/conda-forge/noarch/babel-2.10.3-pyhd8ed1ab_0.tar.bz2#72f1c6d03109d7a70087bc1d029a8eda
 https://conda.anaconda.org/conda-forge/noarch/beautifulsoup4-4.11.1-pyha770c72_0.tar.bz2#eeec8814bd97b2681f708bb127478d7d
 https://conda.anaconda.org/conda-forge/linux-64/cairo-1.16.0-ha61ee94_1011.tar.bz2#0b53c7f7af13244374ef7226bac3f843
 https://conda.anaconda.org/conda-forge/linux-64/certifi-2022.6.15-py310hff52083_0.tar.bz2#a5087d46181f812a662fbe20352961ee
-https://conda.anaconda.org/conda-forge/linux-64/cffi-1.15.0-py310h0fdd8cc_0.tar.bz2#7b7366be82277a5a210e48cc6d25ce26
+https://conda.anaconda.org/conda-forge/linux-64/cffi-1.15.1-py310h255011f_0.tar.bz2#3e4b55b02998782f8ca9ceaaa4f5ada9
 https://conda.anaconda.org/conda-forge/linux-64/docutils-0.17.1-py310hff52083_2.tar.bz2#1cdb74e021e4e0b703a8c2f7cc57d798
 https://conda.anaconda.org/conda-forge/linux-64/gstreamer-1.20.3-hd4edc92_0.tar.bz2#94cb81ffdce328f80c87ac9b01244632
 https://conda.anaconda.org/conda-forge/linux-64/importlib-metadata-4.11.4-py310hff52083_0.tar.bz2#8ea386e64531f1ecf4a5765181579e7e
@@ -188,7 +189,7 @@ https://conda.anaconda.org/conda-forge/linux-64/mpi4py-3.1.3-py310h37cc914_1.tar
 https://conda.anaconda.org/conda-forge/linux-64/numpy-1.23.0-py310h53a5b5f_0.tar.bz2#16493af3907dbd772904e15bf24948d8
 https://conda.anaconda.org/conda-forge/noarch/packaging-21.3-pyhd8ed1ab_0.tar.bz2#71f1ab2de48613876becddd496371c85
 https://conda.anaconda.org/conda-forge/noarch/partd-1.2.0-pyhd8ed1ab_0.tar.bz2#0c32f563d7f22e3a34c95cad8cc95651
-https://conda.anaconda.org/conda-forge/linux-64/pillow-9.1.1-py310he619898_1.tar.bz2#d7052b5cef119518ca362a2ff633a36d
+https://conda.anaconda.org/conda-forge/linux-64/pillow-9.2.0-py310he619898_0.tar.bz2#5808b13c720854aaa3307c6e04cc1505
 https://conda.anaconda.org/conda-forge/linux-64/pluggy-1.0.0-py310hff52083_3.tar.bz2#97f9a22577338f91a94dfac5c1a65a50
 https://conda.anaconda.org/conda-forge/noarch/pockets-0.9.1-py_0.tar.bz2#1b52f0c42e8077e5a33e00fe72269364
 https://conda.anaconda.org/conda-forge/linux-64/psutil-5.9.1-py310h5764c6d_0.tar.bz2#eb3be71bc11a51ff49b6a0af9968f0ed
@@ -197,12 +198,13 @@ https://conda.anaconda.org/conda-forge/linux-64/pysocks-1.7.1-py310hff52083_5.ta
 https://conda.anaconda.org/conda-forge/noarch/python-dateutil-2.8.2-pyhd8ed1ab_0.tar.bz2#dd999d1cc9f79e67dbb855c8924c7984
 https://conda.anaconda.org/conda-forge/linux-64/python-xxhash-3.0.0-py310h5764c6d_1.tar.bz2#b6f54b7c4177a745d5e6e4319282253a
 https://conda.anaconda.org/conda-forge/linux-64/pyyaml-6.0-py310h5764c6d_4.tar.bz2#505dcf6be997e732d7a33831950dc3cf
-https://conda.anaconda.org/conda-forge/linux-64/setuptools-62.6.0-py310hff52083_0.tar.bz2#7fc5b1d6db9f6a9307330303a3edb04d
-https://conda.anaconda.org/conda-forge/linux-64/tornado-6.1-py310h5764c6d_3.tar.bz2#8a5770e6392d29d99c9bc9c3635bba60
+https://conda.anaconda.org/conda-forge/linux-64/setuptools-63.1.0-py310hff52083_0.tar.bz2#4957e3a46761a6c7a3a05233c39ed904
+https://conda.anaconda.org/conda-forge/linux-64/tornado-6.2-py310h5764c6d_0.tar.bz2#c42dcb37acd84b3ca197f03f57ef927d
+https://conda.anaconda.org/conda-forge/noarch/typing-extensions-4.3.0-hd8ed1ab_0.tar.bz2#f3e98e944832fb271a0dbda7b7771dc6
 https://conda.anaconda.org/conda-forge/linux-64/unicodedata2-14.0.0-py310h5764c6d_1.tar.bz2#791689ce9e578e2e83b635974af61743
 https://conda.anaconda.org/conda-forge/linux-64/virtualenv-20.15.1-py310hff52083_0.tar.bz2#7f6c48710ee99edfa3dfa0b54fa6f020
 https://conda.anaconda.org/conda-forge/linux-64/brotlipy-0.7.0-py310h5764c6d_1004.tar.bz2#6499bb11b7feffb63b26847fc9181319
-https://conda.anaconda.org/conda-forge/linux-64/cftime-1.6.0-py310hde88566_2.tar.bz2#90ebffd27e2d482997d3cdb1a60e993a
+https://conda.anaconda.org/conda-forge/linux-64/cftime-1.6.1-py310hde88566_0.tar.bz2#1f84cf065287d73aa0233d432d3a1ba9
 https://conda.anaconda.org/conda-forge/linux-64/cryptography-37.0.2-py310h597c629_0.tar.bz2#7b40622ed00061cc8f803c5ed3c62707
 https://conda.anaconda.org/conda-forge/noarch/dask-core-2022.6.1-pyhd8ed1ab_0.tar.bz2#69655c7e78034d4293130f5a5ecf7421
 https://conda.anaconda.org/conda-forge/linux-64/fonttools-4.33.3-py310h5764c6d_0.tar.bz2#b2171665e9cd3ba4114d90b8da6815c8
@@ -220,7 +222,8 @@ https://conda.anaconda.org/conda-forge/linux-64/pytest-7.1.2-py310hff52083_0.tar
 https://conda.anaconda.org/conda-forge/linux-64/python-stratify-0.2.post0-py310hde88566_2.tar.bz2#a282f30e2e1efa1f210817597e144762
 https://conda.anaconda.org/conda-forge/linux-64/pywavelets-1.3.0-py310hde88566_1.tar.bz2#cbfce984f85c64401e3d4fedf4bc4247
 https://conda.anaconda.org/conda-forge/linux-64/scipy-1.8.1-py310h7612f91_0.tar.bz2#14a7ea0620e4c0801bee756171f4dc03
-https://conda.anaconda.org/conda-forge/linux-64/shapely-1.8.2-py310h7b2ee30_2.tar.bz2#a95baebc52f890fa8bf71f2d3f536ae1
+https://conda.anaconda.org/conda-forge/noarch/setuptools-scm-7.0.4-pyhd8ed1ab_0.tar.bz2#dff6862ca0b54bbeab8ddf657d032920
+https://conda.anaconda.org/conda-forge/linux-64/shapely-1.8.2-py310h5e49deb_3.tar.bz2#5305d80a31c7db98765b52ea95521ff6
 https://conda.anaconda.org/conda-forge/linux-64/sip-6.5.1-py310h122e73d_2.tar.bz2#f485cb3efb4c179928a96fb2e02e6f7e
 https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-napoleon-0.7-py_0.tar.bz2#0bc25ff6f2e34af63ded59692df5f749
 https://conda.anaconda.org/conda-forge/linux-64/ukkonen-1.0.1-py310hbf28c38_2.tar.bz2#46784478afa27e33b9d5f017c4deb49d
@@ -230,12 +233,12 @@ https://conda.anaconda.org/conda-forge/noarch/identify-2.5.1-pyhd8ed1ab_0.tar.bz
 https://conda.anaconda.org/conda-forge/noarch/imagehash-4.2.1-pyhd8ed1ab_0.tar.bz2#01cc8698b6e1a124dc4f585516c27643
 https://conda.anaconda.org/conda-forge/linux-64/matplotlib-base-3.5.2-py310h5701ce4_0.tar.bz2#b038b2e97ae14fea11159dcb2c5abf0a
 https://conda.anaconda.org/conda-forge/linux-64/netcdf4-1.6.0-nompi_py310h947f774_100.tar.bz2#ebde0c4a610be54e818f5407ddc33af7
-https://conda.anaconda.org/conda-forge/linux-64/pango-1.50.7-hbd2fdc8_0.tar.bz2#1cff4bab8ed133d59b7c22fe7bf09263
+https://conda.anaconda.org/conda-forge/linux-64/pango-1.50.8-hbd2fdc8_0.tar.bz2#e76dcd4a0efe0c037929f98c2fd87e10
 https://conda.anaconda.org/conda-forge/noarch/pyopenssl-22.0.0-pyhd8ed1ab_0.tar.bz2#1d7e241dfaf5475e893d4b824bb71b44
 https://conda.anaconda.org/conda-forge/linux-64/pyqt5-sip-12.9.0-py310hd8f1fbe_1.tar.bz2#21ae1ac216cfc85e24dc7c09570ddf31
 https://conda.anaconda.org/conda-forge/noarch/pytest-forked-1.4.0-pyhd8ed1ab_0.tar.bz2#95286e05a617de9ebfe3246cecbfb72f
 https://conda.anaconda.org/conda-forge/linux-64/qt-main-5.15.4-ha5833f6_2.tar.bz2#dd3aa6715b9e9efaf842febf18ce4261
-https://conda.anaconda.org/conda-forge/linux-64/cartopy-0.20.3-py310hb408dcc_0.tar.bz2#32c47109680148344fd76448d808ac75
+https://conda.anaconda.org/conda-forge/linux-64/cartopy-0.20.3-py310he7eef42_1.tar.bz2#a06eff87c5bbd8ece667e155854fec2b
 https://conda.anaconda.org/conda-forge/linux-64/esmpy-8.2.0-mpi_mpich_py310hd9c82d4_101.tar.bz2#0333d51ee594be40f50b157ac6f27b5a
 https://conda.anaconda.org/conda-forge/linux-64/gtk2-2.24.33-h90689f9_2.tar.bz2#957a0255ab58aaf394a91725d73ab422
 https://conda.anaconda.org/conda-forge/linux-64/librsvg-2.54.4-h7abd40a_0.tar.bz2#921e53675ed5ea352f022b79abab076a