Use setuptools_scm versioning

[ewu63]

Purpose

Closes #446. I opted to using setuptools_scm for a few reasons

• It builds the version at package build time, and ships the version file with the package. versioneer vendors some Python code that does this logic at import time which seems way too fragile
• setuptools_scm is used >20x more than versioneer on conda-forge based on search hits
• bump-my-version is a lot more manual IMO - the tag no longer becomes a single source of truth

We will have to adjust some stuff with conda-forge once this is merged, but this should work as-is. A few things to note:

• The versioning scheme is the default guess-next-dev, feel free to suggest alternatives, I have used post-release before. I don't think this ultimately matters since 99% of people should be using a tagged release, but for those that want traceability in a dev env this may matter
• The GitHub archive by default does not generate tag information in the tarball, leading to a loss of version information. This can be remedied via .git_archival.txt file which instructs GitHub to store some extra metadata - this can then be used by e.g. conda-forge when packaging. However, I think it's cleaner to just grab the version from the environment variable - the version is known in the PR. If we think there are other people that may care about this information, we can add this small file, but I have omitted it for now since I don't think people typically care about the archival tarball.

We can use this PR to iterate on this design, and if we like it we can mirror the approach elsewhere in the org. Some extra work was needed here to interface it to meson-python, standard integration with setuptools is trivial since this tool is called....setuptools_scm so it works out of the box.

Expected time until merged

Not urgent.

Type of change

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (non-backwards-compatible fix or feature)
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no API changes)
• Documentation update
• Maintenance update
• Other (please describe)

Testing

Checklist

• I have run ruff check and ruff format to make sure the Python code adheres to PEP-8 and is consistently formatted
• I have formatted the Fortran code with fprettify or C/C++ code with clang-format as applicable
• I have run unit and regression tests which pass locally with my changes
• I have added new tests that prove my fix is effective or that my feature works
• I have added necessary documentation

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 54.22%. Comparing base (a154fc9) to head (29a7f62).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #490   +/-   ##
=======================================
  Coverage   54.22%   54.22%           
=======================================
  Files           1        1           
  Lines         225      225           
=======================================
  Hits          122      122           
  Misses        103      103           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[marcomangano]

This looks cool, I have a few (naive?) questions for now, as I try to understand the process:

• The changes in the .yml are files necessary to prevent the build/test on GHA to break, right?
• Can you expand on the difference between the two (and others?) versioning approaches? My understanding from the original issue is that we aim to get the version from the Github release. Is this related to commits that fall in-between releases, including running the latest version of main?
• The _version.py file is generated in doc/conf.py is a fix for RTD because it does not go through the full meson build which normally generates the file, correct?
• I am not sure about which env variable you refer to when talking about the tarball issues, could you clarify? I agree that any issue related to the archival tarball is secondary anyway.

[ewu63]

• The changes in the .yml are files necessary to prevent the build/test on GHA to break, right?

Yes, it's to checkout the repo with tags under GHA using the checkout action.

• Can you expand on the difference between the two (and others?) versioning approaches? My understanding from the original issue is that we aim to get the version from the Github release. Is this related to commits that fall in-between releases, including running the latest version of main?

If you are referring to the versioning scheme, it is for guessing what the version should be if it is not a tagged commit. For releases this should not matter since we only build on tags, but for local development (editable install for whatever reason, and for CI builds in a PR branch or on main post-merge) the version needs to be generated, and there are different ways of generating a new temporary non-released version. setuptools_scm has docs here and you can also test this out locally by invoking python -m setuptools_scm, e.g. right now it gives 2.16.1.dev10+g15a2e0d8e.

• The _version.py file is generated in doc/conf.py is a fix for RTD because it does not go through the full meson build which normally generates the file, correct?

It is doing two things. Note that we do not install the package into RTD when rendering the docs. So, first it must figure out the version to embed into Sphinx, and it does this via the get_version call. Second, it also writes a _version.py file which stores the version. This makes the package importable (the init.py requires this file, and missing it indicates that something has gone wrong with installation so it fails loudly). The import is used for 1) autodoc which generates the API docs, and 2) using the optionstable to generate the options. So, we need both and it's done here in one call to get_version().

• I am not sure about which env variable you refer to when talking about the tarball issues, could you clarify? I agree that any issue related to the archival tarball is secondary anyway.

I mean that, in the conda-forge recipe here, the version is already available as a jinja variable so we do not need to re-derive it from the source tarball. Conveniently the GitHub tag triggers a PR on conda-forge and that tag metadata info travels with it, so it all works out.

This is fundamentally changing how we version/package so it's good to talk about it and iron out the details.