Package Release Instructions

This document outlines the steps for releasing a versioned JDAViz package to PyPI. Currently, these do not cover submitting package updates to the astroconda channel.

This process currently requires admin-level access to the JDAViz repository, as it relies on the ability to commit to main directly. To do this, it is recommended that you create a temp directory in a different directory where you do your development. Inside this temp directory, git clone the jdaviz repository. This will ensure that you do not have incorrect git remote commands and that you can follow the steps below exactly, without interfering with your development directory.


These instructions are adapted from the Astropy package template releasing instructions.

  1. Ensure GitHub Actions and any other continuous integration is passing in the main repository.

  2. Update the CHANGES.rst file to make sure that all the changes are listed, and update the release date, which should currently be set to unreleased, to the current date in yyyy-mm-dd format.

  3. Run git clean -fxd to remove any untracked files (WARNING: this will permanently remove any files that have not been previously committed, so make sure that you don’t need to keep any of these files).

  4. Generate the source distribution tar file by first making sure the build package is installed and up-to-date:

    pip install build --upgrade

    then creating the source distribution with:

    python -m build --sdist .

    Make sure that generated file is good to go by going inside dist, expanding the tar file, going inside the expanded directory, and running the tests with:

    pip install -e .[test]

    You may need to add the --remote-data flag or any other flags that you normally add when fully testing your package.

  5. Go back to the root of the directory and remove the generated files with:

    git clean -fxd
  6. Add the changes to CHANGES.rst:

    git add CHANGES.rst

    and commit with message:

    git commit -m "Preparing release <version>"
  7. Update the version number to the version you’re about to release by creating a git tag, optionally signing with the -s option:

    git tag v<version>
  8. Add a new section to CHANGES.rst for next version, with a single entry No changes yet, e.g.:

    0.2 (unreleased)
    - No changes yet
  9. Add the changes to CHANGES.rst, where <next_version would be e.g.

    git add CHANGES.rst

    and commit with message:

    git commit -m "Back to development: <next_version>"
  10. Check out the release commit with git checkout v<version>. Run git clean -fxd to remove any non-committed files.

  11. (optional) Run the tests in an environment that mocks up a “typical user” scenario. This is not strictly necessary because you ran the tests above, but it can sometimes be useful to catch subtle bugs that might come from you using a customized developer environment. For more on setting up virtual environments, see virtual_envs, but for the sake of example we will assume you’re using Anaconda. Do:

    conda create -n myaffilpkg_rel_test astropy <any more dependencies here>
    source activate myaffilpkg_rel_test
    python sdist
    cd dist
    pip install myaffilpkg-version.tar.gz
    python -c 'import myaffilpkg; myaffilpkg.test()'
    source deactivate
    cd <back to your source>

    You may want to repeat this for other combinations of dependencies if you think your users might have other relevant packages installed. Assuming the tests all pass, you can proceed on.

  12. If you did the previous step, do git clean -fxd again to remove anything you made there. Run python build sdist --format=gztar to create the files for upload. Then you can upload to PyPI via twine:

    twine upload dist/*

    as described in these instructions. Check that the entry on PyPI is correct, and that the tarfile is present.

  13. Go back to the main branch and push your changes to github:

    git checkout main
    git push --tags origin main

    Once you have done this, if you use Read the Docs, trigger a latest build then go to the project settings, and under Versions you should see the tag you just pushed. Select the tag to activate it, and save.