Appendix C: Developer Notes and Release Procedure

Release Process

Preparatory

1. Create a clean conda environment with the current poppy python version

2. Install poppy (including docs) with pip install -e .[all,test,docs]. If you use zsh you will need to escape the brackets, as \[all,test,docs\]

3. Install pandoc (https://pandoc.org/installing.html)

4. Install graphviz (on a mac, with homebrew, brew install graphviz)

Creating the Release

1. Get the develop branch to the state you would like for the release. This includes all tests passing, both on Github Actions and locally via tox.

2. Locally, checkout the develop branch and ensure it’s current with respect to Github.

3. On github, create a draft release with target “develop”, generate release notes, and copy those release notes into the “relnotes.rst” file in docs (reformatting them into proper ReStructuredText).

4. Locally, move to the docs directory and type make html. Create a branch to fix any warnings or errors, and make a PR to bring those fixes into develop

5. Locally, check out the test_readthedocs branch, update it from develop, and make sure that the generated documentation on readthedocs looks correct.

   1. git checkout test_readthedocs

   2. git reset --hard develop

   3. git push origin test_readthedocs --force (may be upstream instead of origin)

6. Locally, test uploading poppy to test pypi

   1. Create and activate a new empty environment

   2. Install poppy (develop branch) into that environment

   3. pip install build twine

   4. python -m build

   5. twine check dist/*

   6. twine upload --repository-url https://test.pypi.org/legacy/ dist/* --verbose

   7. Create and activate a new empty environment

   8. pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple poppy==VERSION

7. Tag the latest commit in develop with v, being sure to sign the tag with the -s option. (You will need to ensure you have git commit signing via GPG setup prior to this).

   • git tag -s v<version> -m "Release v<version>"

8. Push tag to github: git push upstream v<version> (may be origin instead of upstream)

9. On github, make a PR from develop to stable (this can be done ahead of time and left open, until all individual PRs are merged into develop.).

10. After verifying that PR is complete and waiting for tests to pass, merge it. (Once merged, both the stable and develop branches should match).

11. Release on Github:

    1. On Github, click on “[N] Releases”.

    2. Select “Draft a new release”.

    3. We want to create the release from the tag just added. To do so, select ‘Tags’, then on the line for the latest tag v<version>, at the far right click on the ... button to bring up a small menu containing “Create release”.

    4. Specify the version number, title, and brief description of the release.

    5. Press “Publish Release”.

12. Release to PyPI. This should now happen automatically on Github Actions. This is triggered by a Github Actions build of a tagged commit on the stable branch, so should happen automatically after the PR to stable.

13. Test by creating an empty environment, and installing the new poppy version to this environment using pip install poppy==VERSION

14. Release to AstroConda, via steps below. (Currently deprecated, awaiting transfer to Stenv to update this process)

Releasing a new version through AstroConda

Consider this section deprecated as of version 1.0.3!

AstroConda is currently limited to Python <=3.7, while POPPY only supports Python >=3.8 as of v1.0.3.

Do this after you’ve done the above.

To test that an Astroconda package builds, you will need conda-build:

$ conda install conda-build

1. Fork (if needed) and clone https://github.com/astroconda/astroconda-contrib

2. Edit poppy/meta.yaml to reflect the new version and git_tag.

3. Edit in the git_tag name from git tag in the PyPI release instructions (v0.X.Y).

4. Verify that you can build the package from the astroconda-contrib directory: conda build -c http://ssb.stsci.edu/astroconda poppy

5. Commit your changes to a new branch and push to GitHub.

6. Create a pull request against astroconda/astroconda-contrib.

7. Wait for SSB to build the conda packages.

8. (optional) Create a new conda environment to test the package installation.