Maintainer Notes

These are notes relevant to maintaining the repository

Written by Shannon Osborne, 05/25/2022

---

Continuous Integration

• We use Tox and GitHub Actions
  • The testing options are defined in the tox.ini file
  • And then the tests are applied in the .github/workflows/ci_workflows.yml under the matrix keyword. In each build of the matrix, a python version is defined under python and the tox test is defined under toxenv.
• The CI is run any time a pull request is opened, or a new change is pushed (either directly or to a pull request).
• We normally maintain only 3 Python versions, so as you add new ones, stop using oldest one and shift all the tests up by one version

Dependabot

• Dependabot is a tool that updates the package versions in the requirements.txt file
• It is defined in the .github/dependabot.yml file in the repository
• It is currently set up to run automatically at the beginning of every month. It will check the packages in the requirements.txt file, check if there are newer versions of the packages than is defined in the file, and then opens PRs to update that requirements.txt file with the newer package versions.
• How to handle the updates:
  • You can just close the PRs if you don’t want to deal with them
  • If you do want to deal with them, just check that the CI test labeled “latest” runs successfully (this is the only one you need to check, as all that is changing is the requirements.txt file).
    • As you merge these PRs, rebase the subsequent dependabot PRs to include the previous changes and confirm that all the requirement changes work together and still pass the tests. Rebase the PRs by commenting @dependabot rebase in the PR.

ReadTheDocs

• The requirements file for RTD is docs/requirements.txt
• To access the back end of readthedocs, make an account at readthedocs.org
• You can import the main project, or your fork for testing
• After choosing a project, under the Builds tab you can run builds of the branches to check how they render

Releasing the Code

• WebbPSF and Poppy are currently released on PyPI and Astroconda
  • The PyPI release has been automated using the .github/workflows/publish-to-pypi.yml GitHub Actions file
  • The Astroconda release is not automated and the procedure is detailed below. However, Astroconda may be going away soon, and I am not sure if it will be replaced with anything. This is something to pay attention to, especially since WebbPSF current recommends installing with Astroconda since you can download the data and code together.
• The Release Procedure:
  • Prepare the Data (if necessary)
    • Use the scripts in webbpsf/dev_utils/master_data_release.sh
    • Confirm the data is on central store and ready for use
    • Unzip the resulting zip file someplace.
    • Manually set $WEBBPSF_DATA_PATH to that. Test that it works.
  • Prepare the Code
    • Fill out the release notes in relnotes.html
    • For WebbPSF: Update webbpsf/__init__.py set DATA_VERSION_MIN to the new data's version.
    • For WebbPSF: Update the requirements.txt and setup.cfg to point to the newest poppy version if one was just released.
    • Make sure that the stable and develop branches match each other
    • Confirm tests pass
  • Release on GitHub
    • On the github page, on the right, click on “Releases”
    • Click on "Draft a new release"
    • Specify the new version number, title, and state the reason for the new release.
      • E.g Version: Should be vX.X.X. Target should be “stable"
        • This will create a new tag. You do not have to define the tag locally before this.
      • E.g Title: “Release X.X.X”
      • E.g Description: A one-two sentence description and then link to the release notes
    • Then click "Publish release"
  • Release on PyPI
    • This is done automatically through the .github/workflows/publish-to-pypi.yml file. So as soon as you release the code on GitHub, this action will run. Wait a while and then check on the PyPI website to confirm it has been released.
  • Release on Astroconda
    • Release the Poppy, WebbPSF, and WebbPSF Data versions on Astroconda through the astroconda-contrib repository
    • Create a new branch, change the meta.yaml files for the 3 packages to say the new version number and update the versions of any requirements if they have been changed in the released code.
    • Then open a PR and wait for it to be merged.
  • Check the documentation
    • Readthedocs should automatically build the latest docs from the push to GitHub. But verify this has taken place, and if necessary kick off a manual build.
  • Send out notices
    • Send an email to [email protected]. Brief is good - mention the highlights and link to the online doc release notes.
  • Update your local copy
    • Be sure to pull down the tags and re-run pip install to register the newest version