diff --git a/_images/github-about-example.png b/_images/github-about-example.png
new file mode 100644
index 00000000..d2b96b3f
Binary files /dev/null and b/_images/github-about-example.png differ
diff --git a/_sources/plugins/how-to-guides/distribute-on-library.md b/_sources/plugins/how-to-guides/distribute-on-library.md
index befe1932..400f9d2f 100644
--- a/_sources/plugins/how-to-guides/distribute-on-library.md
+++ b/_sources/plugins/how-to-guides/distribute-on-library.md
@@ -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 ` In Fig. 5, we use a blue “multiple-files” icon to represent the collection of provenance data associated with one single QIIME 2 action.
+ In Fig. 6, we use a blue “multiple-files” icon to represent the collection of provenance data associated with one single QIIME 2 action.
When this icon appears directly within With the exception of the current Result (whose provenance lives in With the exception of the current Result (whose provenance lives in That directory contains: Contents
-provenance/
the files describe the “current” Result.
All remaining icons appear within the artifacts/
subdirectory.
These file collections describe all “parent” Results used in the creation of the current Result, and are housed in directories named with their respective UUIDs.provenance/
, every Action is captured in a directory titled with the Action’s UUID Fig. 6.provenance/
, every Action is captured in a directory titled with the Action’s UUID Fig. 7.
VERSION
(see Rules for identifying an archive)Version-agnostic format guarantees/<UUID>/, and
a file /<UUID>/VERSION
within that directory, formatted as shown below.
Fig. 7 illustrates the Archive file system.
+Fig. 8 illustrates the Archive file system.
The VERSION file format is described above.
@@ -470,11 +469,11 @@The ArchiveFormat
class in v0.py
offers convenience methods for loading and parsing metadata.yaml
files.
Fig. 8 illustrates the format of a Version 0 Archive.
+Fig. 9 illustrates the format of a Version 0 Archive.
action.yaml
and VERSION
files are captured for the current Result and each of its ancestors.
Each Result’s action.yaml
file and associated data artifacts (e.g. sample metadata) are stored in an action
directory alongside that Result’s VERSION
and metadata.yaml
.
Considered together, we can describe these as “provenance files”.
-This structure is illustrated in Fig. 9.
+This structure is illustrated in Fig. 10.
The structure of V1 Archives as a whole is illustrated in Fig. 10.
+The structure of V1 Archives as a whole is illustrated in Fig. 11.
Provenance files for the current Result are stored in /<UUID>/provenance/
.
Provenance files for each ancestor Result are stored in directory at /<root_UUID>/provenance/artifacts/<ancestor_UUID>/
.
The overall directory structure remains identical to a v1 archive (Fig. 9).
+The overall directory structure remains identical to a v1 archive (Fig. 10).
Result-specific citation tags are also written to the transformers
and environment
sections of the action.yaml
files, for the current Result and for all ancestors with registered citations.
A new custom !cite '<citation key>'
tag is use to support this in YAML.
A transformers
section is added between the action
and environment
sections of action.yaml
.
@@ -591,11 +590,11 @@
Fig. 12 illustrates the V5 Archive.
+Fig. 13 illustrates the V5 Archive.
Distributing your plugin on the QIIME 2 Library is a simple process that requires your plugin to conform to the following standards.
-Your plugin must exist as a GitHub repo. Please consult the Distribute plugins on GitHub documentation if you need help with this.
-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.
-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.
-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 of your plugin for users.
-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.
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.
+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 be fully installable via these environment files with no extra steps required.
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.
Your plugin’s source code must be hosted in a GitHub repository. +See Distribute plugins on GitHub if you need help with this.
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 Fig. 1). +This will be used as the short description for your plugin in Library and should be about 300 characters long at the most.
You must have a top-level README.md
in your repository, and this file must be written in GitHub-flavored Markdown.
+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.
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 of your plugin for users.
+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 Distribute plugins 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.
Once you have met the above requirements, open a PR against the library-plugins GitHub repo adding a <my-plugin-name>.yml
file to the plugins
folder. This file must have the following key: value
pairs:
owner: <repo-owner>
-name: <repo-name>
+
+Requesting addition of your plugin to the Library#
+Once you have met the above requirements, open a pull request against the 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: <repository-owner>
+name: <repository-name>
branch: <target-branch>
-docs: <latest-docs-url>
+docs: <latest-documentation-url>
-
-Example PR#
-An example PR 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.
+This pull request 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.
+
+Warning
+Your plugin must be compliant with the above specifications for us to merge your pull request.
+
@@ -558,22 +553,9 @@ Example PR
-