-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
d56a9d0
commit 2a7e437
Showing
2 changed files
with
43 additions
and
39 deletions.
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,51 +1,55 @@ | ||
| (share-on-qiime2-library)= | ||
| # Distribute plugins on QIIME 2 Library | ||
|
|
||
| Distributing your plugin on the QIIME 2 Library is a simple process that requires your plugin to conform to the following standards. | ||
| Distributing your plugin on the QIIME 2 Library is a great way to share your plugin with the QIIME 2 community, and we are regularly adding new functionality to make "the Library" more useful for both users and developers. | ||
|
|
||
| ## A GitHub repo | ||
| Having your plugin listed on the Library requires a few specific things, but as long as these are in place it's a simple process. | ||
|
|
||
| Your plugin must exist as a GitHub repo. Please consult the [](share-on-github) documentation if you need help with this. | ||
| ## Requirements before requesting the addition of your plugin to the Library | ||
|
|
||
| ## A GitHub about section | ||
|
|
||
| Your GitHub repo must have an about section. | ||
|
|
||
| This will be used as the short description for your plugin in Library. It should be 300 or so characters max and should describe what your plugin is. | ||
|
|
||
| ## A top level README | ||
|
|
||
| Your GitHub repo must contain a top level README. This README must be written in GitHub MarkDown. | ||
|
|
||
| This will be rendered as MarkDown on Library and should give a detailed description of your plugin and what it does. | ||
|
|
||
| NOTE: If your README references any resources using paths relative to the root of your repository (images for example) these resources WILL NOT LOAD on QIIME 2 Library. Only resources referenced with absolute URLs will load. This is because we are not cloning and rehosting your assets. We need a valid URL to a resource hosted somewhere online. | ||
|
|
||
| ## Conda environment files for Installation | ||
|
|
||
| This is the highest bar to clear to get your plugin hosted on the QIIME 2 Library. | ||
|
|
||
| More detailed instructions on how to do this are provided at [](facilitating-installation). | ||
|
|
||
| In broad strokes, your repo must include environment.yml files installing your plugin for each QIIME 2 release you support using following naming scheme `<plugin-name>-qiime2-<distro>-<epoch>.yml`. These files must be located in the `/environment-files` folder. | ||
|
|
||
| ### Additional requirements for environment files | ||
|
|
||
| 1. Your plugin must be fully installable via these environment files with no extra steps required. | ||
| 2. Your environment files must NOT contain a `name` field. The end user is expected to provide the name of the environment on the command line when they install. | ||
|
|
||
| # How to add a plugin to the QIIME 2 Library | ||
| Once you have met the above requirements, open a PR against the [library-plugins](https://github.com/qiime2/library-plugins) GitHub repo adding a `<my-plugin-name>.yml` file to the `plugins` folder. This file must have the following `key: value` pairs: | ||
| ````{sidebar} | ||
| ```{figure} ../../_static/github-about-example.png | ||
| --- | ||
| name: github-about-example | ||
| --- | ||
| The *About* section of a GitHub repository. | ||
| ``` | ||
| ```` | ||
|
|
||
| 1. Your plugin's source code must be hosted in a GitHub repository. | ||
| See [](share-on-github) if you need help with this. | ||
| 1. You must have a brief description of your plugin in the *About* field for the repository. | ||
| The *About* field will be on the top-right of your repository's front page (see {numref}`github-about-example`). | ||
| This will be used as the short description for your plugin in Library and should be about 300 characters long at the most. | ||
| 1. You must have a top-level `README.md` in your repository, and this file must be written in [GitHub-flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). | ||
| This will be rendered as Markdown on Library and should give a detailed description of your plugin and what it does. | ||
| If your `README.md` file references any resources (such as images) using paths relative to the root of your repository, these resources WILL NOT LOAD on the Library. | ||
| Only resources referenced with absolute URLs will load. | ||
| 1. Conda environment files must be provided for installation, and they must meet a few formatting requirements. | ||
| This is the highest bar to clear to have your plugin be compatible with the QIIME 2 Library. | ||
| * Your repository must include environment YAML files for each QIIME 2 release you support using the naming scheme `<plugin-name>-qiime2-<distro>-<epoch>.yml`. | ||
| These files must be located in your repository's `/environment-files` folder. | ||
| More detailed instructions on how to do this are provided in [](facilitating-installation). | ||
| One feature that we're working on adding to the Library is a system that can automatically submit PRs against your plugin repository to add new environment files when new QIIME 2 releases come out, to help you keep your plugin up-to-date with QIIME 2 - more on this soon! | ||
| * Your plugin must be fully installable via these environment files with no extra steps required. | ||
| If this isn't possible, you can still distribute your plugin in other ways (e.g., see [](share-on-github)), but it won't work with the QIIME 2 Library. | ||
| * Your environment files must *not* contain a `name` field. | ||
| The install instructions that are created by the Library will include a name for the environment. | ||
|
|
||
| ## Requesting addition of your plugin to the Library | ||
|
|
||
| Once you have met the above requirements, open a pull request against the [library-plugins](https://github.com/qiime2/library-plugins) GitHub repository. | ||
| Your pull request should add a `<my-plugin-name>.yml` file to the `plugins` directory in that repository containing the following key-value pairs: | ||
|
|
||
| ``` | ||
| owner: <repo-owner> | ||
| name: <repo-name> | ||
| owner: <repository-owner> | ||
| name: <repository-name> | ||
| branch: <target-branch> | ||
| docs: <latest-docs-url> | ||
| docs: <latest-documentation-url> | ||
| ``` | ||
|
|
||
| ## Example PR | ||
| This [pull request](https://github.com/qiime2/library-plugins/pull/3/files) illustrates the addition of a plugin to the library in a single atomic commit, and can be used as an example for how to create your pull request. | ||
|
|
||
| An [example PR](https://github.com/qiime2/library-plugins/pull/3) showing the addition of a plugin to the library in a single atomic commit. | ||
|
|
||
| NOTE: Your plugin must be compliant with the above specifications for us to merge your PR. | ||
| ```{warning} | ||
| Your plugin must be compliant with the above specifications for us to merge your pull request. | ||
| ``` |