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

The pvlib test suite contains a decorator that will cause tests to fail if deprecated features are not removed past a specified version.

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. Push the tag to GitHub: git push pvlib [the-tag-name] This will trigger TravisCI to run the test suite on the tagged commit and deploy the package to PyPI as a prerelease.

4. If necessary, remove any features that correspond to tests that failed due to pvlibDeprecationWarnings through the standard pull request process. Repeat the full pre-release procedure with a new tag. No big deal to make multiple pre-releases.

5. Test it:

   2. conda create -n pvlibreltest python=3.7
   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

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. TravisCI 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] TravisCI 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 TravisCI build finished, the new version will be installable with pip install pvlib. Test it!

Manual Upload to PyPI

As of September 2018, TravisCI 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 the following packages to pvlib/meta.yaml under both host and run:
   • scipy
   • pytables
   • numba
   • ephem
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.5 --py 3.6 --py 3.7 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.

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.

Start new version

1. Make a whatsnew file for the next version.