Home » Plugin tutorials »

Updating your qiime2 plugin

This tutorial is for when the QIIME 2 developers have made some changes in the new release that require you to update your plugin, but you made it so long ago that you don’t really have any idea where to start.

I recently went through this process with the 2019.1 update, which switched to Python 3.6, so I’ll be providing some examples specifically for that use case.

Overview

  1. Make whatever changes to your plugin’s codebase that you need to.

  2. Update your plugin version everywhere that it’s needed (including meta.yaml, __init__.py, your README, setup.py, and anywhere else that you have it).

  3. Re-build your plugin using conda-build (don’t forget to: be in the right qiime2 environment, include all the required channels, and use the flag for python 3.6 if needed).

  4. Try installing your new plugin using the --offline flag.

  5. If that works without errors, upload to anaconda.org.

  6. Don’t forget to update your documentation or README explaining what’s new about this version!

That’s all!

A few additional notes about some of the steps:

Update version

If you’re like me and have manually hard-coded the version number in multiple places of your code, you’ll need to find all of those and update them.

Also remember to document this new version (and what’s new or different about it) in your main project documentation, like the repo’s main README.md.

Finally, don’t forget to update any links to the QIIME 2 docs in your documentation too. For example, a link to https://docs.qiime2.org/2018.2/install/ should be changed to https://docs.qiime2.org/2019.1/install/.

Build with conda-build

Double-check the latest dev docs to make sure you have all the necessary flags and channel specifications. The dev team has been working to consolidate packages, so the channels might change.

Also, make sure the latest version of QIIME 2 is used in the following channel specification: -c https://conda.anaconda.org/qiime2/label/r2019.1.

Test the installation

To test the installation locally without uploading the package to anaconda.org, you can run:

conda install --offline /path/to/your/package.tar.bz2

Where the path to your package is what was shown in the final-ish output of conda-build.

Upload to anaconda

Finally, you can upload your package to anaconda.org:

anaconda upload --offline <path/to/your/package>

A few notes:

  • If you made changes to the package’s metadata without changing the version, those metadata changes may not show up on anaconda.org. Keep an eye on this issue for updates on that.

  • You may want to test the conda install in a new and clean environment just to make sure it works.

Document!

Once again, don’t forget to write down what you did and what’s new about this version.

Contributors

  • Claire Duvallet (github: cduvallet), June 2019