Change 'release' flag to be derived from VERSION

Previously setup.py decided if it was in "release mode" by looking at
command-line flags or environment variables.  This meant that
distributed sdists could not tell that they were supposed to be building
in release mode, and so would add on additional local version
information.

Instead, we change our release procedures such that the VERSION file has
a '.dev' postfix if this is a development release, and it doesn't have
one if it isn't.  Development branches such as 'master' and 'dev.major'
will always have this development postfix, but release branches won't.

Author: jakelishman

.github/workflows/build.yml

@@ -43,7 +43,6 @@ jobs:
     needs: deploy_test
     runs-on: ubuntu-latest
     env:
-      CI_QUTIP_RELEASE: 1
       OVERRIDE_VERSION: ${{ github.event.inputs.override_version }}
 
     steps:
@@ -107,9 +106,6 @@ jobs:
     env:
       # Set up wheels matrix.  This is CPython 3.6--3.9 for all OS targets.
       CIBW_BUILD: "cp3[6-9]-*"
-      # Environment variable understood by QuTiP's setup.py to produce a release
-      # version of the wheels.
-      CIBW_ENVIRONMENT: "CI_QUTIP_RELEASE=1"
       OVERRIDE_VERSION: ${{ github.event.inputs.override_version }}
 
     steps:
@@ -160,6 +156,17 @@ jobs:
       - name: Download build artifacts to local runner
         uses: actions/download-artifact@v2
 
+      - uses: actions/setup-python@v2
+        name: Install Python
+        with:
+          python-version: '3.7'
+
+      - name: Verify this is not a dev version
+        shell: bash
+        run: |
+          python -m pip install wheels/*-cp37-cp37m-manylinux2010_x86_64.whl
+          python -c 'import qutip; print(qutip.__version__); assert "dev" not in qutip.__version__; assert "+" not in qutip.__version__'
+
       # We built the zipfile for convenience distributing to Windows users on
       # our end, but PyPI only needs the tarball.
       - name: Upload sdist and wheels to PyPI

VERSION

@@ -1 +1 @@
-4.7.0
+4.7.0.dev

doc/development/release_distribution.rst

@@ -103,9 +103,11 @@ Create a new branch from this, e.g. ::
 
     $ git checkout -b 4.1-release_ready qutip-4.1.X
 
-First change the ``VERSION`` file to contain the new version number.
+First change the ``VERSION`` file to contain the new version number, and remove any ``dev`` postfix if present.
 A major release increments the first number, while a minor release increments the second.
 All numbers after the change digit are reset to 0, so the next minor release after 4.5.3 is 4.6.0, and the next major release after either of these is 5.0.0.
+Alpha, beta and release-candidate releases have a postfix ``.a<n>``, ``.b<n>`` or ``.rc<n>`` repsectively, where ``<n>`` is a counter for the pre-release status, starting from 0.
+For example, the third beta release of version 5.2.1 would have a version of ``5.2.1.b2``.
 The file should contain only the version number in this format, with no extra characters (the automatic line-break at the end is fine).
 
 Next edit ``setup.cfg``.
@@ -124,7 +126,7 @@ The "Development Status" of ``master`` should remain ::
     Development Status :: 2 - Pre-Alpha
 
 because it is never directly released.
-The ``VERSION`` file on ``master`` should reflect the last major or minor release.
+The ``VERSION`` file on ``master`` should reflect the last major or minor release, with a trailing ``.dev`` to indicate that this is a development branch.
 
 
 .. _docbuild:

pyproject.toml

@@ -1,6 +1,7 @@
 [build-system]
 requires = [
     "setuptools",
+    "packaging",
     "wheel",
     "cython>=0.29.20",
     "numpy>=1.16.6,<1.20",

setup.py

@@ -10,6 +10,7 @@
 import warnings
 
 # Required third-party imports, must be specified in pyproject.toml.
+import packaging.version
 from setuptools import setup, Extension
 import distutils.sysconfig
 import numpy as np
@@ -49,15 +50,9 @@ def process_options():
 
 def _determine_user_arguments(options):
     """
-    Add the 'release' and 'openmp' options to the collection, based on the
-    passed command-line arguments or environment variables.
+    Add the 'openmp' option to the collection, based on the passed command-line
+    arguments or environment variables.
     """
-    options['release'] = (
-        '--release' in sys.argv
-        or bool(os.environ.get('CI_QUTIP_RELEASE'))
-    )
-    if '--release' in sys.argv:
-        sys.argv.remove('--release')
     options['openmp'] = (
         '--with-openmp' in sys.argv
         or bool(os.environ.get('CI_QUTIP_WITH_OPENMP'))
@@ -104,7 +99,7 @@ def _determine_compilation_options(options):
 
 def _determine_version(options):
     """
-    Adds the 'short_version' and 'version' options.
+    Adds the 'short_version', 'version' and 'release' options.
 
     Read from the VERSION file to discover the version.  This should be a
     single line file containing valid Python package public identifier (see PEP
@@ -117,27 +112,31 @@ def _determine_version(options):
     """
     version_filename = os.path.join(options['rootdir'], 'VERSION')
     with open(version_filename, "r") as version_file:
-        version = options['short_version'] = version_file.read().strip()
-    VERSION_RE = r'\d+(\.\d+)*((a|b|rc)\d+)?(\.post\d+)?(\.dev\d+)?'
-    if re.fullmatch(VERSION_RE, version, re.A) is None:
-        raise ValueError("invalid version: " + version)
+        version_string = version_file.read().strip()
+    version = packaging.version.parse(version_string)
+    if isinstance(version, packaging.version.LegacyVersion):
+        raise ValueError("invalid version: " + version_string)
+    options['short_version'] = str(version.public)
+    options['release'] = not version.is_devrelease
     if not options['release']:
-        version += "+"
+        # Put the version string into canonical form, if it wasn't already.
+        version_string = str(version)
+        version_string += "+"
         try:
             git_out = subprocess.run(
                 ('git', 'rev-parse', '--verify', '--short=7', 'HEAD'),
                 check=True,
                 stdout=subprocess.PIPE, stderr=subprocess.PIPE,
             )
             git_hash = git_out.stdout.decode(sys.stdout.encoding).strip()
-            version += git_hash or "nogit"
+            version_string += git_hash or "nogit"
         # CalledProcessError is for if the git command fails for internal
         # reasons (e.g. we're not in a git repository), OSError is for if
         # something goes wrong when trying to run git (e.g. it's not installed,
         # or a permission error).
         except (subprocess.CalledProcessError, OSError):
-            version += "nogit"
-    options['version'] = version
+            version_string += "nogit"
+    options['version'] = version_string
     return options