diff --git a/book/plugins/how-to-guides/automate-testing.md b/book/plugins/how-to-guides/automate-testing.md index 237dbdf..ccff3fd 100644 --- a/book/plugins/how-to-guides/automate-testing.md +++ b/book/plugins/how-to-guides/automate-testing.md @@ -26,6 +26,15 @@ 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. +``````{Note} +Before creating any GHAs for your plugin, you'll start by creating a top-level directory within your plugin's repository with the following name: +``` +.github/workflows/ +``` + +This naming structure is what allows Github to identify any relevant actions or workflows that should be run within your repository, and is where all of your GHA files should be created. +`````` + Here is what the basic structure of your GHA will look like: ``` @@ -49,7 +58,7 @@ This will typically be your `main` branch, but may differ if you've customized t - ``: the name of your repository on GitHub - `--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-.yml`). +Your GHA file will be stored under the `.github/workflows/` directory in your repository, and you can use the same name as your Github Action for the filename (e.g., `ci-.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 `` or a pull request against ``. @@ -82,6 +91,8 @@ jobs: env-file-name: development--environment.yml> ``` +This GHA file will also be stored under the `.github/workflows/` directory in your repository, and you can use the same name as your Github Action for the filename (e.g., `cron-.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). diff --git a/book/plugins/how-to-guides/facilitate-installation.md b/book/plugins/how-to-guides/facilitate-installation.md index 22d3e9c..9036ea9 100644 --- a/book/plugins/how-to-guides/facilitate-installation.md +++ b/book/plugins/how-to-guides/facilitate-installation.md @@ -37,6 +37,15 @@ With the following terms defined: - ``: the name of your plugin repository on GitHub (this often will be the same as your plugin's package name, e.g., `q2-dwq2`) - `` (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` +``````{Note} +In the examples provided in this guide, we utilize the `released` channel for our QIIME 2 packages (i.e. `packages.qiime2.org/qiime2///released`). +If you are interested in creating and/or sharing instructions for installing a version of your plugin that relies on one of our development environments (meaning the current development cycle environment prior to an official release version), you'll want to target the `passed` channel of that particular distribution. +Here's an example of what this channel might look like (as of Sept. 2024, prior to the 2024.10 release): +``` +https://packages.qiime2.org/qiime2/2024.10/amplicon/passed +``` +`````` + Using the above guidelines, you can provide the following install instructions for your users: ``` conda env create \