Table of Contents
- Contributing a Bioconductor Package
- Starting the Submission Process
- What to Expect
- Adding a Web Hook
- Submitting Related Packages
- Additional Actions
Contributing a Bioconductor Package
This repository is used to contribute new packages to the Bioconductor project for the analysis and comprehension of high-throughput genomic data. Please
Review the package submission process.
Ensure that your package conforms to our package guidelines.
Ask questions about new package submission on the bioc-devel mailing list.
By using this service, please note that:
Your package code will be visible to the general public, where anyone can see it.
The build reports and comments during the review process are public.
Any GitHub user may add comments to the package review.
You are submitting a package for inclusion in Bioconductor; the build service we provide is meant only for individuals submitting Bioconductor packages.
Starting the Submission Process
To submit a package to Bioconductor:
Create your own GitHub repository, containing source code structured as an R package. The source code must be in a default 'master' branch of your GitHub repository.
Add SSH public key(s) to your GitHub account. The SSH key pair will be used after package acceptance for updating the Bioconductor git repository.
Open a new issue. Complete the issue by adding the link to your repository, and confirming that you understand the review process, package guidelines, and maintainer responsibilities. Provide the name of your package as the 'Title' of the issue.
Add a webhook to your repository. The webhook means that any commit to the default 'master' branch automatically triggers a new package build.
What to Expect
A new package is initially labeled as '1. awaiting moderation'. A Bioconductor team member will take a very brief look at your package, to ensure that it is intended for Bioconductor. Appropriate packages will be re-labelled '2. review in progress'.
The package will be submitted to the Bioconductor build system. The system will check out your package from GitHub. It will then run
R CMD buildto create a 'tarball' of your source code, vignettes, and man pages. It will run
R CMD checkon the tarball, to ensure that the package conforms to standard R programming best practices. Finally, the build system will run
R CMD BiocCheckto ensure that the package conforms to Bioconductor BiocCheck standards. The system will perform these steps using the 'devel' version of Bioconductor, on three platforms (Linux, Mac OS X, and Windows). After these steps are complete, a link to a build report will be appended to the new package issue. Avoid surprises by running these checks on your own computer, under the 'devel' version of Bioconductor, before submitting your package.
If the build report indicates problems, modify your package and commit changes to the default branch of your GitHub repository. If there are problems that you do not understand, seek help on the bioc-devel mailing list.
To trigger a new build, include a version bump in your commit, e.g., from
Once your package builds and checks without errors or (avoidable) warnings, a Bioconductor team member will provide a technical review of your package. Other Bioconductor developers and users with domain expertise are encouraged to provide additional community commentary. Reviewers will add comments to the issue you created.
Respond to the issues raised by the reviewers. You must respond to the primary reviewer, and are strongly encouraged to consider community commentary. Typically your response will involve code modifications; commit these to the default branch of your GitHub repository to trigger subsequent builds. When you have addressed all concerns, add a comment to the issue created in step 2 to explain your response.
The reviewer will assess your responses, perhaps suggesting further modifications or clarification. The reviewer will then accept your package for inclusion in Bioconductor, or decline it. The label '2. review in progress' will be replaced by '3a. accepted' or '3b. declined'.
If your package is accepted, it will be added to Bioconductor's Subversion source control repository and to the nightly 'devel' builds. All packages in the 'devel' branch of the repository are 'released' to the user community once every six months, in approximately April and October.
Adding a Web Hook
To add a web hook:
Go to your repository page on GitHub. The link to it will look something like this:
yourpackagenamewill be different.
Settings, which is currently located towards the top, on the right-hand side of the page.
In the left hand
Optionssection, click on
Paste the following URL into the
Payload URLbox, leaving the other settings alone:
Confirm that the
Content typedrop-down menu has
The page will be updated to include a link to the web hook. Click on the link. A 'Recent Deliveries' area should contain a single request. Click on the Request and view the "Response" tab. There should be a green
200response code, with body
ping received, Bioconductor/Contributions webhook ok.
Subsequent pushes to the default
master branch of your
repository will now trigger builds (only if the package version
has been bumped), and the build reports will be
posted to the issue you created in this repository. Note that pushes
to branches that are not
master, or non-default branches, are ignored.
Submitting Related Packages
Sometimes it is appropriate to contribute more than one package at a time. The most common case is when a software package has a companion experiment data package used for illustrative purposes in the vignette. Remember to avoid circular dependencies between packages.
Start by submitting the package that can be installed without a dependency on any of the other packages you are submitting (this is usually the experiment data package). Do this by creating a new issue as described above.
Continue working with this package until it builds and checks without error on any platform.
Submit additional packages to the same issue. Do this by posting a comment containing a line like:
Include only one
AdditionalPackageline per comment. Wait until this related package builds before submitting further related packages.
AdditionalPackagecomment must be posted by the same GitHub user who created the issue. Also, the initial package submitted in the issue must have completed the 'moderation' step. If these conditions are not met, the additional package will not build.
Add a webhook for each additional package, so that any changes (accompanied by a version bump) trigger a new build.
To change the repository of your package during the review process:
- Edit the first comment in the issue associated with your package. Change the Repository: link to point to your new repository.
- Add a webhook to the new repository (and remove the corresponding web hook from the old repository).
- Post a comment in your issue, including @mtmorgan, indicating that you have changed the repository.
- Once the comment is acknowledged, bump the package version in the new repository to trigger a new build.
To remove an AdditionalPackage: dependency, e.g., because you have identified AnnnotationHub or other resources that make your additional package unnecessary:
- Delete or edit all comments with an
To debug package commits that don't trigger a response on the corresponding issue:
Verify that the web hook is in place.
Review 'Recent Deliveries', especially those marked as failures (red triangle with exclamation mark). Click on the checksum, look at the 'Response' body.
If the response body says 'Failed to parse JSON', verify that the web hook (in your repository, 'Settings', 'Webhooks', 'Edit' the web hook you've added) has 'Content type:' equal to
After debugging, click the 'Redeliver' button.
The following pages contain more information about package submission.
- Package Submission.
- Package Guidelines.
- The above and many other developer resources are available at the developers' page.
If you have a question not answered above, please ask on the bioc-devel mailing list.