Release Procedure - PyTables/PyTables GitHub Wiki

• Fork the project into your Github personal account.

• Set the __version__ to the appropriate value in tables/_version.py.

• Open a Pull Request. The Development Team will be aware of the release progress and can help with it.

$ python3 -m tables.tests.test_all --heavy

If possible run the tests under Linux (or Mac) and Windows. Make sure you run the tests in a clean environment with supported versions of the dependencies (most importantly HDF5 and cython). Note that cython>=0.29.32 is required for PyTables > 3.8.0.

• Make sure that RELEASE-NOTES.txt do contain notes about the most important changes.

• Update the "Release timeline" section in doc/source/release_notes.rst.

• Maybe update docs with copyright dates and something like that.

• Update the ANNOUNCE.txt.in

Merge release branch into master and tag the merge commit with the version number; if possible, create a signed and annotated tag: git tag -s -a -m 'PyTables vX.Y.Z' vX.Y.Z master. Push the tag and master: git push origin vX.Y.Z master.

Note: The files generated below are also available as GHA artifacts from the "Wheels" workflow of releases/** and master branches, as well as master tags. Thus, the two first (building) steps can be skipped by downloading and unpacking the cibw-wheels-*.zip and dist.zip archives from the "Wheels" workflow of the vX.Y.Z tag into an empty directory (then removing the requirements.txt file).

• Generate a tarball with the version to release, the MD5 checksum file, PDF doc and HTML doc tarballs (pytables-<VERSION>.md5, RELEASE_NOTES-<VERSION>.rst, pytablesmanual-<VERSION>.pdf and pytablesmanual-<VERSION>-html.tar.gz):

   $ make dist
  

• Make binary wheels (tables-<VERSION>-<PYTHON>-<OS>_<ARCH>.whl).

• Use twine to upload the distribution and wheels to PyPI. If you made the files yourself:

  $ twine check dist/*
  $ twine upload dist/*
  

  If you unpacked the archives from GHA (in the current directory):

  $ twine check tables-<VERSION>.tar.gz tables-<VERSION>-*.whl
  $ twine upload tables-<VERSION>.tar.gz tables-<VERSION>-*.whl
  

  If you have 2FA activated in PyPI, twine upload will request your API token (not your password). If you haven't uploaded to PyPI in a while or you have activated 2FA, you may want to have a look at Migrating to PyPI.org or Uploading the distribution archives (mind you, 2FA tokens are requested at pypi.org, not test.pypi.org).

• Test wheel installation from PyPI in a separate virtual environment in a temporary directory:

  $ mkdir /tmp/foo
  $ cd /tmp/foo
  $ python3 -m venv VENV
  $ . VENV/bin/activate
  $ pip install tables  # check that it installs the new version
  $ python -m tables.tests.test_all
  

• (Optional) submit a PR to conda-forge: https://github.com/conda-forge/pytables-feedstock (although they should be able to notice the new release and update packages themselves)

• Update the HTML manual on-line

  • make html (you may want to create a virtual environment & run pip install -e '.[doc]' in it), or unpack pytablesmanual-<VERSION>-html.tar.gz available in GHA artifacts (see above)
  • Test that the manual can be browsed online by running python -m http.server in doc/html, then browsing to http://localhost:8000/. Do check that the "Library Reference" does contain docstrings and not just headers, and do test the search function (see #994). If anything is broken, try to build the HTML manual locally.
  • Manually copy doc/html/* into the pytables.github.com repo (keep additional files in the repo, e.g. rsync -a /path/to/doc/html/ /path/to/pytables.github.com/), commit with "Update to PyTables v<VERSION>" and push the latter

• Create a new release in GitHub from the release tag, make it latest, with title "Release v<VERSION>", in the body paste the release notes block for this particular version (including its heading "Changes from X to Y"). You'll need to convert the reST to Markdown, some hints:

  • Reformat headings to use #, ##…
  • Unwrap split lines.
  • Replace :PR:.\([0-9]+\). with #\1
  • Replace :issue:.\([0-9]+\). with #\1
  • Replace :commit:.\([0-9]+\). with commit \1

• Create a post-release commit on github (see previous ones, use comment "Post-vX.Y.Z release actions done") and push it:

  • update the __version__ in tables/__init__.py file (--> __version__+1.dev0)
  • update the release notes with a section for __version__+1.dev0 (with the placeholder line)
  • restore the announce file template (with the placeholder line)

• Update the milestones in github:

  • update the milestone to match the final version number (if needed)
  • create a new milestone for the next release
  • move remaining issue associated to the current milestone to the next one
  • close the current milestone

Post a general announcement to:

• pytables-users
• pytables-dev
• Tweet or toot about it and rejoice!

Be nice and include ANN: in the email's subject (e.g. "ANN: PyTables X.Y.Z released"); you may use the ANNOUNCE.txt.in of the release-tagged commit, be careful to replace every occurrence of @VERSION with X.Y.Z and remove the local variables block at the end of the file.

Don't bother to PGP-sign the announcements sent to Google Groups lists, as Google has not yet figured out how to add the list footer without breaking the original message.

Also remember that you can subscribe without a Google account by sending an email to [email protected].