Prepare release 0.17.1

CHANGES.txt

@@ -1,3 +1,19 @@
+v0.17.1 (2026-07-28)
+--------------------
+
+No library changes: this release exists so the packaging and documentation fixes below are
+carried by a tag, since Read the Docs builds `stable` from the most recent one.
+
+- Fixed: the Read the Docs build failed with "No module named 'pkg_resources'". The docs
+  requirements pinned Sphinx 2.2.0, which imports pkg_resources, and setuptools removed it in
+  81.0. Only the two direct documentation dependencies are pinned now, with lower bounds.
+- Fixed: the docstring of dwca.star_record.StarRecordIterator contained invalid
+  reStructuredText, which surfaced as a warning once v0.17.0 added the module to the API
+  reference.
+- Packaging: pyproject.toml now declares the build backend, so builds resolve setuptools in
+  an isolated environment. Building v0.17.0 with an older setuptools produced an sdist
+  filename PyPI rejects.
+
 v0.17.0 (2026-07-28)
 --------------------
 

doc/contributing.rst

@@ -29,19 +29,33 @@ The online docs will be updated automagically after pushing to GitHub.
 Releasing at PyPI
 -----------------
 
-* (Ensuring it works -also on Windows-, the test coverage is good and the documentation is updated)
-* Update the packaging (version number in dwca/version.py, CHANGES.txt, ...) then run:
-    
-::
+* Check the GitHub Actions run is green (it covers Linux, macOS and Windows) and that the
+  documentation is up to date.
+* Update ``dwca/version.py`` and ``CHANGES.txt``, and get that merged to ``main``.
+* From a clean checkout of ``main``::
 
-    $ python setup.py sdist bdist_wheel
-    $ twine upload dist/*
+    $ pip install --upgrade build twine
+    $ rm -rf build dist
+    $ python -m build
+    $ twine upload dist/python_dwca_reader-X.Y.Z*
 
-* Create a new tag and push it to GitHub
-
-::
+* Tag the released commit and push the tag::
 
     $ git tag vX.Y.Z
-    $ git push origin --tags
+    $ git push origin vX.Y.Z
+
+Four things that have caught us out, all of them worth the extra keystrokes:
+
+* Build with ``python -m build``, not ``python setup.py sdist bdist_wheel``. The latter uses
+  whichever setuptools happens to be first on your PATH, and anything older than 69.3 names
+  the sdist ``python-dwca-reader-X.Y.Z.tar.gz``, which PyPI rejects outright.
+* Delete ``build/`` first. It shadows the ``build`` module, so ``python -m build`` fails with
+  a confusing "No module named build".
+* Upload only the files for the version being released. ``twine upload dist/*`` also tries to
+  re-upload previous releases, and the whole command fails on the first one that already
+  exists. ``twine upload --skip-existing dist/*`` is the alternative: it skips whatever is
+  already on PyPI.
+* Read the Docs builds ``stable`` from the most recent tag, so a documentation fix only shows
+  up there once a release contains it.
 
 .. _coverage.py: http://nedbatchelder.com/code/coverage/

dwca/version.py

@@ -1 +1 @@
-__version__ = "0.17.0"
+__version__ = "0.17.1"