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.

Pre-releases

Pre-releases help with two things:

1. ensuring that changes to the pvlib build/install procedures work as expected (the CI, setup.py, 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. Run pytest pvlib

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

5. 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.

6. Test it:

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

https://en.wikipedia.org/wiki/Pvlib_python

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

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!

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...

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

1. Activate the base conda environment conda activate base.
2. In a non-pvlib directory, conda skeleton pypi pvlib.
3. Add some optional dependencies to pvlib/meta.yaml under both host and run. Check packages against the conda-forge meta.yaml discussed below. Packages may include:
   • statsmodels
   • pytables
   • numba
   • ephem
   • netcdf4
4. Add noarch: python to the build section.
5. Build the package for the "noarch" system type (compatible with Linux, Mac, and Windows) and for multiple Python versions. conda build --py 3.6 --py 3.7 --py 3.8 --py 3.9 pvlib/
6. Upload to Anaconda.org: anaconda upload -u pvlib ~/miniconda3/conda-bld/noarch/pvlib-0.6.0a2-py_0.tar.bz2

The package is now installable with conda install -c pvlib pvlib

Test it:

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

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

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.
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 often takes hours for conda-forge to build the new package. Eventually you can test it using the same procedure outlined above, but change the package name to pvlib-python and the channel name to conda-forge: conda create -n pvlibreltest python=3.7 pvlib-python -c conda-forge

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.

Update Zenodo badge

1. Edit DOI in README.md to display the Zenodo identifier for the release. The identifier is found at zenodo.org, search for pvlib.

Update Wikipedia version

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

Start new version

1. Make a whatsnew file for the next version.