Skip to content

Latest commit

 

History

History
176 lines (128 loc) · 7.12 KB

best_practices.md

File metadata and controls

176 lines (128 loc) · 7.12 KB
Raw

Best practices and standards for Bioconductor Docker Images

This document aims to outline some of the policies we have set to better maintain the Bioconductor Docker images and also community contributions.

Table of Contents

How to contribute a new Docker image

  1. The Docker image should be on a GitHub repository owned by the author. The name of the repository should follow the convention bioconductor_docker_<image-name>. All image names should be lowercase.

  2. Once the image is ready to be submitted, submit the repository as an issue through contributions page. For more instructions on how to submit, https://github.com/Bioconductor/Contributions.

  3. The first iteration of the contribution should be developed from the "devel" (master branch) branch of the base image i.e bioconductor/bioconductor_docker:devel.

  4. Once accepted, the repository will be cloned under the Bioconductor organization with full read/write access to the Github repository (https://github.com/Bioconductor).

  5. The Docker Hub organization for Bioconductor will be controlled by the Core team, and builds will be triggered through a push to the GitHub repository which the maintainer will have access to. A new tag for a branch will be added by the Core team at the time of release to enable builds on Docker Hub. We hope to automate some of this in the future.

  6. The author should demonstrate, through Docker Hub builds before acceptance, that the image builds successfully. This guide on Docker Hub is very helpful, https://docs.docker.com/docker-hub/builds/link-source/.

  7. The repository should have an open source license in the LICENSE.txt file. Core Bioconductor packages are typically licensed under Artistic-2.0.

  8. The DESCRIPTION file should contain a field BiocType: Docker

  9. At the time of RELEASE, bioconductor/bioconductor_docker will provide a new RELEASE_X_Y branch. The core team will create a new branch in the Github repository with the tag RELEASE_X_Y. If the contributed image depends on bioconductor/bioconductor_docker the tag will be updated to bioconductor/bioconductor_docker:RELEASE_X_Y.

[ Back to top ]

Best Practices and Standards for a Docker image and Dockerfile

  1. For every repository submitted the Dockerfile is in the top level directory.

  2. Docker images should be based on the bioconductor/bioconductor_docker:devel images, so that they can inherit all the installed packages and customization, but that is not strictly required.

  3. Images should have a Dockerfile which is clearly defined and documented.

  4. Images should clean up extraneous files created as part of the installation process, to optimize the space used by the image layers. Avoid reinstalling existing software, as this adds another layer without removing the original installtion layer. Please check https://www.fromlatest.io if you have any questions regarding how to optimize the Dockerfile.

  5. The README.md file will act as the vignette for the images. The README.md should have a clear reasoning on what this Dockerfile provides, i.e additional tools or packages on top of bioconductor/bioconductor_docker. Remember there is very little value in providing the same image with a couple of extra packages on top of it as users can install these packages themselves.

  6. Add metadata fields identifying the image in the Dockerfile like below,

LABEL name="bioconductor/bioconductor_docker_<image-name>" \
      version="0.99.0" \
      url="https://github.com/Bioconductor/bioconductor_docker_<image-name>" \
      maintainer="[email protected]" \
      description="Description of my image" \
      license="Artistic-2.0"

These Metadata fields allow the image to be identified by the user.

  1. Add build badges in your README.md file for the image. This can be easily generated by https://shields.io/category/build, like below

     [![Docker Build Status](https://img.shields.io/docker/cloud/build/bioconductor/bioconductor_docker.svg)](https://hub.docker.com/r/bioconductor/bioconductor_docker/builds/)

  2. The RELEASE_X_Y image should be maintained without a build failure. Similar to packages, changes to the RELEASE_X_Y images should be for bug fixes only.

[ Back to top ]

Deprecation policy

We expect Docker images to follow the same deprecation policy as Bioconductor packages.

Criteria for image deprecation

  1. docker build fails.

    The image must build successfully at each Bioconductor release. All efforts will be made to keep the image in Bioconductor if the maintainer is actively attempting to fix.

    If an image is broken for an extended period of time the maintainer will be given a final 6 week notice. If the image is not fixed by the end of the 6 weeks, an 'End-of-Life' process will be started.

  2. Inactive maintainer

    The maintainer listed in the Dockerfile under LABEL maintainer="[email protected]" must be responsive to questions on the support site, image related emails from users, build failures on Docker Hub and queries from Bioconductor team members. Broken images should be fixed in a timely manner.

    If you are unable to fix your image or no longer wish to maintain your image, please contact the Bioc-devel mailing list.

End of Life process

Step 1: Deprecation

The :devel image will be marked with a Deprecated warning. The README file of the Github repository will be updated, along with the build badge.

If at any time prior to the next release, the required criteria are met (e.g., the image returns to active maintenance, perhaps after ‘adoption’ by a third party) the warning is removed.

Step 2: Defunct

Any :devel image marked Deprecated, at the start of a release cycle will be marked as Defunct. At the start of the following release cycle, the image will be removed from the Bioconductor organization on Docker Hub.

For more details take a look at the Package deprecation page http://bioconductor.org/developers/package-end-of-life/.

Reversing End of Life

A deprecated image can be un-deprecated if it is fixed before the next Bioconductor release. To have an image un-deprecated, please contact Bioc-devel mailing list.

[ Back to top ]