deploy: 5ee8820

_sources/plugins/how-to-guides/automate-testing.md

@@ -0,0 +1,115 @@
+(automate-testing)=
+# Automate testing of your plugin
+
+Automating testing of your plugin is a good way to ensure that you are alerted to issues with your plugin before your users discover them.
+This How-to guide provides instructions on automating testing of your plugin using GitHub Actions, and assumes that have configured installation of your plugin as described in [](facilitating-installation).
+
+```{important}
+You will need to adjust the environment file versions in the two Github Actions described below with each new QIIME 2 release.
+These are specified as `ci-<repository-name>` and `cron-<repository-name>` in the text below.
+We plan to develop functionality as part of the QIIME 2 Library that will help to automate this process for plugin developers, but as of now (16 August 2024) this process is manual.
+```
+
+## Automated Testing using Continuous Integration (CI) and Github Actions (GHA)
+
+The weekly development builds of the QIIME 2 distributions can help you make sure your code stays current with the distribution(s) you are targeting as you can automate your testing against them.
+[](setup-dev-environment) will help you install the most recent successful development metapackage build (again, usually weekly, but sometimes the builds fail and take time to debug).
+
+There are a couple of things that we recommend implementing to help you ensure that your plugin remains compatible within the QIIME 2 ecosystem (discussed below).
+
+### Configure Continuous Integration (CI) testing
+
+Continuous Integration testing is designed to regularly install and run your plugin's unit tests in the targeted QIIME 2 distributions or your custom distribution.
+
+To implement this, you'll need to create a Github Action (GHA) that will be triggered each time you make a commit to your repository - either through a pull request (PR) or a direct commit to one of your remote branches.
+Github Actions can be a bit confusing to set up.
+We recommend the online course, [*GitHub Automation for Scientists*](https://hutchdatascience.org/GitHub_Automation_for_Scientists), developed by the [ITCR Training Network](https://www.itcrtraining.org/), before moving forward.
+Once you've read through this (and hopefully played around with a few of the toy examples provided therein), you can start to put together a CI workflow based the examples provided here.
+
+Here is what the basic structure of your GHA will look like:
+
+```
+name: ci-<repository-name>
+on:
+  pull_request:
+    branches: ["<target-branch>"]
+  push:
+    branches: ["<target-branch>"]
+jobs:
+  ci:
+    uses: qiime2/distributions/.github/workflows/lib-community-ci.yaml@dev
+    with:
+      github-repo: <repository-name>
+      env-file-name: <target-epoch>-<package-name>-environment.yml
+```
+
+With the bracketed terms defined as:
+- `<target-branch>`: the branch that should be used when running the GHA
+This will typically be your `main` branch, but may differ if you've customized the branch structure of your repository.
+- `<repository-name>`: the name of your repository on GitHub
+- `<target-epoch>-<package-name>-environment.yml`: the name of your environment file. If you haven't created this yet, refer back to [](facilitating-installation) before continuing.
+
+Your GHA file will be stored under under `.github/workflows/` in your repository, and you can use the same name as your Github Action for the filename (e.g., `ci-<repository-name>.yml`).
+Note that the extension will also be `.yml` (same as your environment file(s)).
+
+After creating this file and pushing it to the main branch of your repository, this GHA should run anytime there is a commit to `<target-branch>` or a pull request against `<target-branch>`.
+
+### Configure weekly automated testing
+
+Keeping your package up to date with all of the downstream dependencies can feel like a lot of work and hassle, and it can be.
+Unfortunately, software is never "done", and that's important to understand if you're distributing software for the community to use.
+It's going to require maintenance because software is always changing, and the more dependencies your plugin has, the more likely it is that updates to one of your dependencies will necessitate changes to your plugin (e.g., due to an API change in the dependency).
+Performing automated weekly test builds of your plugin will help you keep your package up to date and alert you as issues arise so you can discover them and address them on your own schedule, before it becomes a problem for your users.
+
+In addition to running your unit tests for each commit and/or pull request against your plugin's `<target-branch>`, we recommend implementing regularly scheduled testing of your plugin against the development environments for the QIIME 2 distributions and/or plugins that it relies on.
+
+The process for this will be very similar to the GHA discussed above.
+The main differences are that your plugin's environment will be configured with the latest development version of the relevant distribution(s), rather than a specified release version, and that the GHA will be triggered at specific times rather than based on specific events (commits or pull requests).
+We suggest having these tests run on a weekly basis to make sure you have ample time between QIIME 2 releases to fix any dependency conflicts or issues from code changes that may arise.
+
+Here's the basic structure of the GHA you'll create to initiate these scheduled tests against your target distribution's development environment:
+```
+name: cron-<repository-name>
+on:
+  workflow_dispatch: {}
+  schedule:
+    - cron: 0 0 * * SUN
+jobs:
+  ci:
+    uses: qiime2/distributions/.github/workflows/lib-community-ci.yaml@dev
+    with:
+      github-repo: <repository-name>
+      env-file-name: development-<repository-name>-environment.yml>
+```
+
+Relative to the GHA example above, the differences are:
+
+  - The trigger for this action (i.e., `on`) is either manual (`workflow_dispatch`) or a schedule (`cron`) (previously it was commits and pull requests).
+  You can utilize the manual trigger under your repository's `actions` tab if you'd like to re-run these scheduled tests sooner than the next scheduled occurrence (if you're troubleshooting a test failure or upstream dependency issue).
+  You can adjust the schedule to any frequency you'd prefer, but we recommend weekly testing to ensure you catch anything that may have fallen out of sync well in advance of the upcoming release.
+  More information on the formatting for cron scheduling can be found [here](https://www.ibm.com/docs/en/db2/11.5?topic=task-unix-cron-format).
+  - The environment file that is targeted by this action is different than what's used in your CI testing (`development` vs `<target-epoch>`).
+  The idea here is that your CI testing is targeting official release versions of your QIIME 2 environment, while these scheduled tests are targeting the current development environment.
+  In order to support this, you'll need to create a new 'development' environment file with each QIIME 2 release that looks like the following:
+
+```
+channels:
+- https://packages.qiime2.org/qiime2/<next-epoch>/<target-distribution>/passed
+- conda-forge
+- bioconda
+dependencies:
+  - qiime2-<target-distribution>
+  - pip
+  - pip:
+    - <repository-name>@git+https://github.com/<owner>/<repository-name>.git@<target-branch>
+```
+
+With the bracketed terms defined as:
+- `<next-epoch>`: the next QIIME 2 release epoch.
+QIIME 2 releases are scheduled for the first Wednesday of April and October, so this value is always predictable.
+For example, if the most recent release was 2024.10, your `<next-epoch>` would be 2025.4.
+- `<target-distribution>`: the QIIME 2 distribution that your plugin should be installed under (e.g., `amplicon`, or `metagenome`).
+- `<target-branch>` (optional): the branch of your repository that testing will be performed against. If not specified, this will default to your repository's *Default branch* (e.g., `main`). If you don't include this, you should leave off the `@` symbol following `.git`.
+
+You can set up any additional GHAs on your repository that you feel will be beneficial to your plugin and general development workflow.
+The actions outlined here are what the QIIME 2 developers recommend having to maintain an active and usable plugin.

_sources/plugins/how-to-guides/facilitate-installation.md

@@ -0,0 +1,198 @@
+(facilitating-installation)=
+# Facilitating installation of your plugin for users
+
+(install-in-existing-distro)=
+## Installing your plugin on top of an existing QIIME 2 Distribution (recommended)
+
+The easiest way to instruct users to install your plugin in the context of an existing QIIME 2 Distribution is to create a conda environment file that they can use to install a specific distribution of QIIME 2 including your plugin, all while using a single command.
+
+In the top-level directory of your plugin, create the following directory:
+
+```
+environment-files/
+```
+
+Within this directory, create environment file(s) for current and/or past installable versions of your plugin.
+You can name them with a pattern like `<target-epoch>-<package-name>-environment.yml` (for example, `2024.05-q2-dwq2-environment.yml`).
+
+The contents of your environment file should look something like this:
+
+```
+channels:
+- https://packages.qiime2.org/qiime2/<target-epoch>/<target-distribution>/released
+- conda-forge
+- bioconda
+dependencies:
+  - qiime2-<target-distribution>
+  - pip
+  - pip:
+    - <package-name>@git+https://github.com/<owner>/<repository-name>.git@<target-branch>
+```
+
+With the following terms defined:
+- `<target-epoch>`: the QIIME 2 epoch that your plugin should be installed under (e.g., `2024.5` or `2024.10`)
+- `<target-distribution>`: the QIIME 2 distribution that your plugin should be installed under (e.g., `amplicon`, or `metagenome`)
+- `<package-name>`: your plugin's package name (e.g., `q2-dwq2`)
+- `<owner>`: the github organization your plugin is hosted under, or your personal github account name
+- `<repository-name>`: the name of your plugin repository on GitHub (this often will be the same as your plugin's package name, e.g., `q2-dwq2`)
+- `<target-branch>` (optional): the relevant branch that users should be utilizing to install your plugin - if not specified, this will default to your repository's *Default branch* (e.g., `main`). If you don't include this, you should leave off the `@` symbol following `.git`
+
+Using the above guidelines, you can provide the following install instructions for your users:
+```
+conda env create \
+ -n <target-epoch>-<package-name> \
+ -f https://raw.githubusercontent.com/<owner>/<repository-name>/<target-branch>/environment-files/<target-epoch>-<package-name>-environment.yml
+```
+
+Again, you'll fill in the values enclosed in the `<` and `>` brackets.
+As above, `<target-branch>` is the branch that your users should install, but in this case it is required.
+(Often this will be `main`.)
+
+This method also provides a familiar way for users to install new versions of your plugin.
+By maintaining release branches on your repository, you can create a new environment file for each release that targets the corresponding release branch.
+
+As an example, your branch structure could look like the following:
+
+```
+release-2024.5 # the 2024.5 release of your plugin
+release-2024.10 # the 2024.10 release of your plugin
+main # your main branch, usually what would be installed for a "development" installation
+```
+
+You could then have environment files and install instructions for these different branches that look like the following (in this example, `amplicon` is the target distribution):
+
+`````{tab-set}
+````{tab-item} release-2024.5
+
+Environment file: `2024.5-q2-dwq2-environment.yml`
+
+```
+channels:
+- https://packages.qiime2.org/qiime2/2024.5/amplicon/released
+- conda-forge
+- bioconda
+dependencies:
+  - qiime2-amplicon
+  - pip
+  - pip:
+    - q2-dwq2@git+https://github.com/caporaso-lab/[email protected]
+```
+
+Install instructions:
+
+```
+conda env create \
+ -n q2-dwq2 \
+ -f https://raw.githubusercontent.com/caporaso-lab/q2-dwq2.git/main/environment-files/2024.5-q2-dwq2-environment.yml
+```
+
+````
+
+````{tab-item} release-2024.10
+
+Environment file: `2024.10-q2-dwq2-environment.yml`
+
+```
+channels:
+- https://packages.qiime2.org/qiime2/2024.10/amplicon/released
+- conda-forge
+- bioconda
+dependencies:
+  - qiime2-amplicon
+  - pip
+  - pip:
+    - q2-dwq2@git+https://github.com/caporaso-lab/[email protected]
+```
+
+Install instructions:
+
+```
+conda env create \
+ -n q2-dwq2 \
+ -f https://raw.githubusercontent.com/caporaso-lab/q2-dwq2.git/main/environment-files/2024.10-q2-dwq2-environment.yml
+```
+
+````
+
+````{tab-item} main (development)
+
+Environment file: `development-q2-dwq2-environment.yml`
+
+```
+channels:
+- https://packages.qiime2.org/qiime2/2024.10/amplicon/released
+- conda-forge
+- bioconda
+dependencies:
+  - qiime2-amplicon
+  - pip
+  - pip:
+    - q2-dwq2@git+https://github.com/caporaso-lab/q2-dwq2.git
+```
+
+Install instructions:
+
+```
+conda env create \
+ -n q2-dwq2 \
+ -f https://raw.githubusercontent.com/caporaso-lab/q2-dwq2.git/main/environment-files/development-q2-dwq2-environment.yml
+```
+
+````
+`````
+
+In the above examples, the `main` branch location houses all of the environment files, regardless of which release they're associated with.
+This is reflected by each `conda env create` command referring to a URL like `https://raw.githubusercontent.com/.../main/environment-files/...`.
+We recommend having all of your environment files available on a single branch, which makes finding and referencing them easier.
+
+## Installing your plugin using the Tiny Distribution and any custom required plugins
+
+If you are working on a plugin that is not compatible with one of our existing distributions but depends on some plugins in those distributions, you can utilize a similar approach to that outlined [above](install-in-existing-distro) but with a more customized environment file.
+As a reminder, while this approach is fairly straightforward to implement, **we don't recommend this if the option presented above is possible for your plugin** as this will be more difficult for us to assist you with and for you to help your users troubleshoot.
+As long as you are aware of these limitations and wish to proceed in this way, you can follow the steps below.
+
+Start by following the same suggestions presented above for creating an `environment-files/` directory and naming your environment file.
+We'll put some different content in the environment file(s) this time.
+
+As an example, the contents of an environment file for a plugin that depends on the `q2-feature-table` and `q2-composition` plugins would look something like this:
+
+```
+channels:
+- https://packages.qiime2.org/qiime2/2024.5/tiny/released
+- https://packages.qiime2.org/qiime2/2024.5/amplicon/released
+- conda-forge
+- bioconda
+dependencies:
+  - qiime2-tiny
+  - q2-feature-table
+  - q2-composition
+  - pip
+  - pip:
+    - q2-dwq2@git+https://github.com/caporaso-lab/[email protected]
+```
+
+In this example, the plugin being developed (`q2-dwq2`) requires `q2-feature-table` and `q2-composition`, but we're assuming that it's not compatible with the entire amplicon distribution.
+Because this plugin still requires a basic QIIME 2 environment, the `qiime2-tiny` distribution will be installed from the first channel listed.
+The `q2-feature-table` and `q2-composition` dependencies are not part of the `qiime2-tiny` distribution however, but are a part of the amplicon distribution.
+Therefore the second channel listed is the `amplicon` channel.
+We then list the dependencies as `qiime2-tiny` (the `tiny` distribution) and then the two additional plugins.
+Those are all followed by the installation of the `q2-dwq2` plugin, as in the previous example.
+
+Generally, your customized environment files will be structured as follows:
+```
+channels:
+- https://packages.qiime2.org/qiime2/<target-epoch>/tiny/released
+- https://packages.qiime2.org/qiime2/<target-epoch>/<target-distribution>/released
+- conda-forge
+- bioconda
+dependencies:
+  - qiime2-tiny
+  - <other-plugin-dependency-1>
+  - <other-plugin-dependency-2>
+  - pip
+  - pip:
+    - q2-dwq2@git+https://github.com/caporaso-lab/q2-dwq2.git@<target-branch>
+```
+
+In this case, `<other-plugin-dependency-1>` and `<other-plugin-dependency-2>` are plugins that are distributed through `<target-distribution>`.
+Note that if you have plugin dependencies that span multiple distributions, you'll need to include each distribution's channel in your environment file.

_sources/plugins/how-to-guides/maximize-compatibility.md

@@ -11,18 +11,20 @@ A complete list of artifact classes and formats available in a deployment of QII
 (Some are missing documentation - we'd [love your help addressing that](https://github.com/caporaso-lab/developing-with-qiime2/issues/97).)
 If you do need to create new artifact classes, you can add these in your own plugin(s).
 
-The Caporaso Lab is not taking on new responsibility for distributing plugins right now (i.e., integrating them in the distributions they develop and maintain), but we are currently (23 April 2024) developing new mechanisms for helping you share your plugin or other tools (see [](plugin-how-to-publicize)) that will ultimately replace the [QIIME 2 Library](https://library.qiime2.org).
+The Caporaso Lab is not taking on new responsibility for distributing plugins right now (i.e., integrating them in the distributions they develop and maintain), but is currently (15 August 2024) developing new mechanisms for helping you share your plugin or other tools (see [](plugin-how-to-publicize)) that will ultimately replace the [QIIME 2 Library](https://library.qiime2.org).
 
 You can consider the existing distributions to be foundations that you can build on, or you can create and distribute your own conda metapackages.
 Some guidance on each of these approaches:
    - Your install instructions can indicate that a user should install whichever distribution you depend on (e.g., `tiny`, `amplicon`, or `metagenome`) and then illustrate how to install your plugin(s) in that environment however it makes sense (e.g., `conda` or `pip`). Complete install instructions are drafted for you in the `README.md` of plugins that you build using our template (see [](plugin-from-template)).
    - Alternatively, you can compose and share your own distribution of plugins (e.g., building from the `tiny` distribution) that captures the set of functionality you’d like to share.
 
-Either of these approaches is totally fine.
-The former is an easier starting point.
+Either of these approaches is totally fine, with the following caveats.
+The former is an easier starting point, and will allow us to provide more troubleshooting assistance for any installation issues that users may encounter.
+While the latter provides you with more flexibility in your environment construction, our assistance with any install issues or environment conflicts that users may run into will be more limited (and will ultimately be your responsibility to troubleshoot and resolve).
 
-The weekly development builds of the QIIME 2 distributions can help you make sure your code stays current with the distribution(s) you are targeting as you can automate your testing against them.
-[](setup-dev-environment) will help you install the most recent successful development metapackage build (again, usually weekly, but sometimes the builds fail and take time to debug).
+With the above information in mind, refer to [](facilitating-installation) for instructions on how to support either of these approaches.
+
+## Getting Feedback on your Plugin
 
 You can request feedback on your plugin as a whole from more experienced QIIME 2 developers by reaching out through the {{ developer_discussion }}.
 However, be cognizant of the fact that doing code review takes a long time to do well: you should only request this when you feel like you have a final draft of the plugin that you'd like to release, and expect that the reviewer may point out that there is a bunch more work that should be done before you release.