ToolShed Readiness Checklist
============================
The process from writing a tool to getting it into a ToolShed can be long and
arduous and confusing. This checklist should assist in making sure you have
done everything required for a great, easy to use Galaxy Tool!
Before ToolShed
---------------
- A `GitHub `__ repository should exist for your wrappers, either one you own, or perhaps you are contributing to the `IUC's repository `__.
- A tool directory should exist for the specific set of tools or related functionality you are wrapping.
- Check `Bioconda `__ for available packages required for the tool you are wrapping. If they do not exist, you may need to create them. The `IUC `__ will be happy to help you with doing this.
- `Planemo `__ should be installed (``pip install -U planemo``)
- You will need to have credentials to access your ToolShed (either the `Main
ToolShed `__, or your local Galactic ToolShed).
Creating the Tool Wrapper (XML File)
------------------------------------
- Review the `IUC's Best Practices for Tools `__.
- Consult the `Galaxy Tool XML File schema `__.
- Create your tool wrapper with a command like ``planemo tool_init --id 'tool_name' --name 'Tool description'``.
- Alternatively, you could copy and modify `an existing IUC wrapper `__.
- Give your tool an appropriate ``ID`` and ``name`` by consulting the `IUC's Best Practices for Tools `__. The ``ID`` is usually the same as the name of the tool XML file and directory.
- Define a `Tool Version `__ for the wrapper. If it is the first wrapper, is recommended to use the same version as the tool in the requirement.
- Add a short tool `Description `__.
- Fill in the `Requirements `__ section with the conda package name and version number for the tool and its dependencies.
- Add the `Version Command `__ that specifies the command to get the tool’s version.
- Add the `Command `__ section. The command to run the tool must be within `CDATA tags `__, written in `Cheetah `__ and conform to `PEP 8 `__. You should add `Exit Code detection `__ and **use single quotes** for all Input and Output parameters of type ``data``, ``data_collection`` and ``text``.
- Supply at least one `Input `__ with a description of parameters. Add `Validators `__ to user input fields.
- Supply at least one `Output `__ with a description of parameters. For Output that is optionally created, use `Filters `__.
- Supply at least one `Test `__. The primary output is a good choice for testing. Don't forget the use of ``sim_size`` if variable data is included.
- Add a `Help `__ section written in `valid reStructuredText `__ within CDATA tags.
- Add a `Citation `__ section with a citation for the tool, preferably a `DOI `__.
- If your tool uses `built-in data `__:
- Provide the comment-only ``tool-data/data_table_name.loc.sample`` file
- Provide the comment-only ``tool_data_table_conf.xml.sample`` file
- Check that the XML elements and parameters attributes are in the `Order specified in the Best Practices `__.
- If you have a collection of related tools you can try to avoid duplicating XML by using a `Macros XML file `__
- Use 4 spaces for indentation.
Testing Your Tool
-----------------
- Fill the ``test-data`` directory with at least one input file and the expected
output file.
- It is strongly encouraged that you use small test data sets, ideally
under 1 Mb. Every Galaxy instance that downloads your tool will
have to download an entire copy of the test data. If the sum of your
test-data files is larger than that, consider use of ``contains`` and
test for a small subset of the output, see the `CWPair2 example `__.
- If your tool uses tool-data:
- Provide a ``tool_data_table_conf.xml.test`` file, which is an uncommented version of ``tool_data_table_conf.xml.sample`` containing the path to the loc file for testing: ````
(Please note the use of ``${__HERE__}`` to indicate the directory where the tool is).
- Provide the .loc file: ``test-data/data_table_name.loc``
- For a good example of how to test parameters from data tables, please see the `Bowtie example `__.
- Check your tool XML with ``planemo lint``.
- Run functional tool tests in a local Galaxy with ``planemo test``.
- Serve the tool on a local Galaxy instance for manual verification that everything looks as expected with the ``planemo serve`` command.
Uploading Your Tool to a ToolShed
----------------------------------
- Ensure you have a ``.shed.yml`` file with the appropriate contents.
- Check the ``.shed.yml`` with ``planemo shed_lint``.
- Create the remote repository with ``planemo shed_create --shed_target [toolshed|your_local_shed:9000]``.
Adding Your Tool to the IUC Repository
--------------------------------------
- `Create an issue on IUC GitHub `__, tracking your progress and ensuring that no one else is working on the same tool.
- Fork IUC GitHub on your GitHub account.
- Clone the corresponding repository ``git clone https://github.com//tools-iuc tools-iuc``
- Within that folder, create a corresponding branch with ``git checkout -b
$branch_name``. You might name it after the tool.
- After you have tested your tool and are completely happy with it (per
previous sections of this document), add your tool and all associated data,
then Commit the changes with ``git commit -m "I changed X, Y, and Z"``. Finally push your changes to github with ``git push origin $branch_name``.
- Go to the `IUC's Repository `__ and click on 'Compare & Pull Request'.
- Add a comment describing what the tool and any extra information that might
be needed (E.g. "I had some trouble with the data tables, can someone please
double check them").
- The IUC will review your tool for inclusion.
- Note that any Python code submitted to IUC must conform to `PEP 8 `__, in order to pass the `flake8 `__ `Travis CI `__ testing.