This document outlines the steps needed to properly release a new version of the VisPy python package.

1. Review github issues and pull requests. Avoid leaving any package breaking issues unresolved.
2. If it exists, review milestone's issues for the new version. Resolve all pre-release issues (code issues, etc).
3. Review documentation and verify accuracy against recent changes.
4. Verify most recent Travis-CI and Appveyor tests completed successfully.

Releases notes are auto-generated from GitHub pull requests based on labels and the settings in the .github_changelog_generator configuration file in the root of the vispy repository. To update the release notes (CHANGELOG):

0. Install github_changelog_generator and follow installation instructions for creating a GitHub token for authorized access to GitHub.

1. Run github_changelog_generator on the command line substituting the previous version tag and the new version tag name (git tag not created yet):

   github_changelog_generator --user vispy --project vispy --since-tag v0.6.1 --future-release v0.6.2 -o ""

   Note: If you installed the tool in your user directory the binary github_changelog_generator may be located in a directory like ~/.gem/ruby/2.5.0/bin/ (instead of being on your PATH).

2. Copy the text that is output from the above command (except the last line about github_changelog_generator generating this output) and paste it to the top of the CHANGELOG.md file just below the # Release Notes title.

3. Update README with any announcements or major changes

4. Update year range in LICENSE.txt

5. Commit these changes.

VisPy documentation is stored in the doc directory of the main VisPy repository and is a sphinx project. The website is automatically rendered, including gallery images using sphinx-gallery, as part of Continuous Integration.

1. Commit and push any changes to the main branch. Wait for tests to pass on all CIs (GitHub Actions, etc).

2. Tag the release and push the tag to GitHub:

   git tag -a "v0.5.2" -m "Version 0.5.2"
   git push --follow-tags
   

   The GitHub Actions should automatically build wheels and an sdist package and deploy them to PyPI.

3. Verify new release on PyPI: https://pypi.org/project/vispy/

4. From your local main branch, create a new maintenance branch for new major or minor versions:

   git checkout -b maint/X.Y
   

   Or switch to the existing maintenance branch for bug fix releases:

   git checkout maint/X.Y
   

5. Merge main in to the branch, if needed (git merge main) and push this branch to GitHub:

   git push -u origin maint/X.Y
   

6. Switch back to the main branch: git checkout main

This should be done automatically by the CI operations from the main branch.

Make a release on GitHub for version vX.Y.Z via the GitHub interface (this triggers a Zenodo DOI update and tags automatically; follow existing releases for consistent naming)

1. See https://doi.org/10.5281/zenodo.592490
2. It should update automatically with the GitHub release.

1. See https://github.com/conda-forge/vispy-feedstock
2. The conda-forge bots should automatically create a new pull request when a release is detected on PyPI. This may take an hour or so to get discovered. The recipe maintainers (which should include Vispy core developers) will merge this pull request, if all tests have completed.
3. After merge the packages will get built from the main branch of the feedstock and uploaded to the anaconda conda-forge channel. Depending on the time to build the package (not very long), it can take an addition 60-120 minutes for all package indexes to be updated for users to see the vispy package available with their local conda package managers.

TODO: Instructions, who is responsible?

General email template:

To: Scipy-Users and python-announce-list and post on vispy mailing list

Subject: ANN: VisPy X.Y released

Hi all,

<basic notes and updates>

<small list of changes if it makes sense>

What is VisPy?
--------------

VisPy is a Python library for interactive scientific visualization that is designed to be fast, scalable, and easy to use. VisPy leverages the computational power of modern Graphics Processing Units (GPUs) through the OpenGL library to display very large datasets. Applications of VisPy include:

High-quality interactive scientific plots with millions of points.
Direct visualization of real-time data.
Fast interactive visualization of 3D models (meshes, volume rendering).
OpenGL visualization demos.
Scientific GUIs with fast, scalable visualization widgets (Qt or Jupyter Notebook via jupyter_rfb).

See the Gallery and many other example scripts on the VisPy website (http://vispy.org/).

Upgrading
---------

VisPy supports Python 3.x on Linux, Mac OSX, and Windows. VisPy's heavy use of the GPU means that users will need to have modern and up-to-date video drivers for their system. VisPy can use one of many backends, see the documentation for details. We strive to keep backwards compatibility with older versions of VisPy, but interfaces are still being designed to best serve our users. As such, some things may have changed that break your existing usage. See the Release Notes (linked below) for more information on what has changed and contact the VisPy developers for help with any problems you run into.

Links
-----

GitHub: https://github.com/vispy/vispy
Website: http://vispy.org/
Gitter (for chat): https://gitter.im/vispy/vispy
Mailing list: https://groups.google.com/forum/#!forum/vispy
Release Notes: https://github.com/vispy/vispy/blob/main/CHANGELOG.md

Contributing
------------

Help is always welcome. See our Contributor's Guide for information on how you can participate:

https://vispy.org/dev_guide/contributor_guide.html

Thanks,
X