Release procedures

This wiki has notes on how to release new versions of pvlib-python.

It assumes that the git remote pvlib points to pvlib/pvlib-python:

git remote add pvlib git@github.com:pvlib/pvlib-python.git

Before making any releases, you need to double check that your clone is up to date with the pvlib remote:

1. git checkout master
2. git fetch pvlib
3. git merge pvlib/master --ff-only

If the last step fails you need to git checkout -b dirtymaster; git checkout master; git reset --hard pvlib/master. Your work is saved in dirtymaster.

Alternatively, one can use the GitHub Releases interface to accomplish some of the git tag/git push steps.

Find broken links

Sphinx allows to check that all external links in the documentation are working properly. For this purpose, a dedicated builder exists: linkcheck.

To run this builder:

1. Change the working directory to docs/sphinx
2. Run python -m sphinx --builder linkcheck --show-traceback source build/linkcheck (make sure you have sphinx==7.3)
3. Wait ~4 minutes for the builder to finish and show all problems at resolving external links.

Pre-releases

Pre-releases help with two things:

1. ensuring that changes to the pvlib build/install procedures work as expected (the CI, pyproject.toml, etc.)
2. checking that we've remembered to remove deprecated features.

It's no big deal to make multiple pre-releases.

1. Bring your clone up to date with the pvlib remote (see above)

2. Make an alpha, beta, or release candidate tag (e.g. git tag v0.6.0-alpha or git tag v0.6.0-rc.1). See semver.org

3. Reinstall pvlib from your clone (pip install .) so that the new version number is reflected in your development environment.

4. Run pytest pvlib

5. If necessary, remove any features that correspond to tests that failed due to pvlibDeprecationWarnings through the standard pull request process.

6. Push the tag to GitHub: git push pvlib [the-tag-name] This will trigger Github Actions to deploy the package to PyPI as a prerelease.

7. Test it:

   2. conda create -n pvlibreltest python=3.8
   3. conda activate pvlibreltest
   4. pip install pvlib --pre
   5. python -c 'import pvlib'

Final release

1. Finalize the whatsnew file using the standard pull request process:
   • Add/edit release date
   • Add names/usernames of anyone that is missing from the Contributors list. Be sure to include people that created issues or commented on issues/pull-requests.
   • Clean up common rst mistakes such as line wraps that are not indented and apostrophes (') instead of back-ticks (`).

Choose one of the options below for making the release.

From GitHub (recommended)

1. Make the GitHub release using the releases page. The tag should be e.g. v0.6.0. The title is the version name. The description can be a link to the version-specific whats new section on readthedocs e.g. v0.5.2. GitHub actions will build the package and push it to PyPI.

From your clone

1. Bring your clone up to date with the pvlib remote (see above)
2. Create a git tag: git tag v0.6.0
3. Push the tag: git push pvlib [the-tag-name] GitHub actions will build the package and push it to PyPI.
4. Make the GitHub release using the releases page. The tag must be the same as was previously pushed. The title is the version name. The description can be a link to the version-specific whats new section on readthedocs e.g. v0.5.2

After the GitHub action finishes, the new version will be installable with pip install pvlib. Test it!

Update conda-forge packages

1. Fork the pvlib-python-feedstock.
2. Update the recipe/meta.yaml file with the new version and the md5 hash of the .tar.gz file.
3. Double check the version numbers of packages specified in recipe/meta.yaml E.g. numpy, pandas. Update version numbers if necessary. Make sure to add any new dependencies, including build-time dependencies like setuptools_scm.
4. Make a pull request with the update.
5. Complete the check marks on the conda-forge pull request template.
6. Merge the pull request (assuming the tests pass).

It sometimes takes hours for conda-forge to build the new package. Eventually you can test it using a procedure like this:

1. conda create -n pvlibreltest python=3.8 pvlib -c conda-forge
2. conda activate pvlibreltest
3. python -c 'import pvlib'

Then test it on another kind of operating system, if possible.

Post-release checklist:

Start next version

1. Close the GitHub milestone for the released version; create a milestone for the next version if it doesn't already exist.
2. Make a whatsnew file for the next version, and link it in the whatsnew.rst so that the new page is included in documentation builds for the next development cycle. This should be done in a pull request immediately after the release.

Publicize release

• Send an announcement to the pvlib-python Google group.
• Notify NumFOCUS and ask them to include in a note in the next newsletter. The latest contact as of 2021-09-03 was Arliss Collins arliss@numfocus.org 2020-04-22 was Walker Chabbott walker@numfocus.org 2019-12-19 was Nicole Foster nicole@numfocus.org (please update as needed).
• Optionally send announcements to NumFOCUS Google group and PyData Google group. The easiest way to update all Google groups at the same time is to send a single email to all 3 simultaneously, as long as you are a member from the same Google account to all 3 groups.
• Also optionally send an email to the following Python mailing lists: scipy-user@python.org, numpy-discussion@python.org, python-announce-list@python.org after registering for each list. Same as with Google groups, it's easiest to send one email to all 3 lists at the same time.
• Here's an example email template:

Subject: [ANN] pvlib-python <vX.Y.Z>: predicting power for solar energy
From: Release Manager <my-google-acct@gmail.com>
To: pvlib-python@googlegroups.com, numfocus@googlegroups.com, pydata@googlegroups.com, \
    scipy-user@python.org, numpy-discussion@python.org, python-announce-list@python.org

pvlib has a new <major|minor> release, <vX.Y.Z>

Release Notes:  https://pvlib-python.readthedocs.io/en/<vX.Y.Z>/whatsnew.html

PyPI:           https://pypi.org/project/pvlib/

Read the Docs:  https://pvlib-python.readthedocs.io/en/latest/

GitHub:         https://github.com/pvlib/pvlib-python

Highlights:
   - dropped support for <package>
   - new <features>
   - updated <something>

This is a <major|minor> release, so there are a few <breaking API changes|bug fixes>.
Users are advised to read the release notes before updating.

Check the Zenodo integration

1. Check that Zenodo successfully detected and imported the new version. The DOI in README.md should already automatically link to the latest version.

Update Wikipedia version

1. Edit the infobox on the wikipedia page to list the new version.

Backup instructions

These instructions should not be needed, but are included here just in case.

Manual Upload to PyPI

A GitHub action is configured to automatically push tagged commits to PyPI. So, manual upload should not usually be necessary for pvlib releases. But if you need to...

Note: these instructions are out of date and need to be updated to use pyproject.toml instead of setup.py.

From the root pvlib-python directory:

1. Bring your clone up to date with the pvlib remote (see above)
2. Ensure that your working directory is clean. Make a fresh clone or remove any added files. Carefully run git clean if necessary.
3. Build a source distribution python setup.py sdist
4. Build wheels python setup.py bdist_wheel --universal
5. Upload to PyPI twine upload dist/* as described by the PyPA.

The package is now installable with pip install pvlib. Test it!

Upload to Anaconda.org (obsolete)

v0.9.4 was the last version to be distributed via the pvlib anaconda channel, so the release procedure no longer involves uploading a distribution to anaconda.org (see #1622). For reference, the original content of this section is preserved here: https://github.com/pvlib/pvlib-python/wiki/Release-procedures/c0a6471e3813742e75b73e6f0ba874e2bb87daf0#upload-to-anacondaorg