diff --git a/appendix.Rmd b/appendix.Rmd index eef5f7389..1bc27b16c 100644 --- a/appendix.Rmd +++ b/appendix.Rmd @@ -4,6 +4,8 @@ ## 0.3.0 +* 2020-02-06, add guidance about Bioconductor dependencies (#246). + * 2020-02-06, add package logo guidance (#217). * 2020-02-06, add one CRAN gotcha: single quoting software names(#245, [`@aaronwolen`](https://github.com/aaronwolen)) diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 8df234bc8..05393a4ed 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -251,15 +251,22 @@ Please do not list editors as contributors. Your participation in and contributi * You can run examples with `devtools::run_examples()`. Note that when you run R CMD CHECK or equivalent (e.g., `devtools::check()`) your examples that are not wrapped in `\dontrun{}` or `\donttest{}` are run. * In addition to running examples locally on your own computer, we strongly advise that you run examples on one of the CI systems, e.g. Travis-CI. Again, examples that are not wrapped in `\dontrun{}` or `\donttest{}` will be run, but for those that are you can add `r_check_args: "--run-dontrun"` to run examples wrapped in `\dontrun{}` in your `.travis.yml` (and/or `--run-donttest` if you want to run examples wrapped in `\donttest{}`). -## Package dependencies +## Package dependencies {#pkgdependencies} * Use `Imports` instead of `Depends` for packages providing functions from other packages. Make sure to list packages used for testing (`testthat`), and documentation (`knitr`, `roxygen2`) in your `Suggests` section of package dependencies (if you use `usethis` for adding testing infrastructure via [`usethis::use_testthat()`](https://usethis.r-lib.org/reference/use_testthat.html) or a vignette via [usethis::use_vignette()](https://usethis.r-lib.org/reference/use_vignette.html), the necessary packages will be added to `DESCRIPTION`). If you use any package in the examples or tests of your package, make sure to list it in `Suggests`, if not already listed in `Imports`. +* If your (not Bioconductor) package depends on Bioconductor packages, make sure the installation instructions in the README and vignette are clear enough even for an user who is not familiar with the Bionconductor release cycle. + + * Should the user use [`BiocManager`](https://www.bioconductor.org/install/index.html#why-biocmanagerinstall) (recommended)? Document this. + + * Is the automatic installation of Bioconductor packages by `install.packages()` enough? In that case, mention that the user needs to run `setRepositories()` if they haven't set the necessary Bioconductor repositories yet. + + * If your package depends on Bioconductor after a certain version, mention it in DESCRIPTION and in the installation instructions. + * Specifying minimum dependencies (e.g. `glue (>= 1.3.0)` instead of just `glue`) should be a conscious choice. If you know for a fact that your package will break below a certain dependency version, specify it explicitly. But if you don't, then no need to specify a minimum dependency. In that case when a user reports a bug which is explicitly related to an older version of a dependency then address it then. An example of bad practice would be for a developer to consider the versions of their current state of dependencies to be the minimal version. That would needlessly force everyone to upgrade (causing issues with other packages) when there is no good reason behind that version choice. - * For most cases where you must expose functions from dependencies to the user, you should import and re-export those individual functions rather than listing them in the `Depends` fields. For instance, if functions in your package produce `raster` objects, you might re-export only printing and plotting functions from the **raster** package. * If your package uses a _system_ dependency, you should @@ -341,6 +348,10 @@ Once your package is on CRAN, it will be [regularly checked on different platfor * the [CRAN checks API](https://github.com/ropenscilabs/cchecksapi) maintained by rOpenSci, that provides [badges](https://github.com/ropenscilabs/cchecksapi#badges). You can add one of them to the README of your package via [`rodev::use_cchecks_badge()`](https://docs.ropensci.org/rodev/reference/use_cchecks_badge.html). +## Bioconductor gotchas + +If you intend your package to be submitted to, or if your package is on, Bioconductor, refer to [Bioconductor packaging guidelines](https://www.bioconductor.org/developers/package-guidelines/). + ## Further guidance * _R Packages_ by Hadley Wickham and Jenny Bryan is an excellent, readable resource on package development which is available for [free online](https://r-pkgs.org/) (and [print -- link to former version by Hadley Wickham as the new version is not published yet as of June 2019](https://amzn.com/1491910593?tag=r-pkgs-20)). diff --git a/pkg_ci.Rmd b/pkg_ci.Rmd index 5c0d22623..910626907 100644 --- a/pkg_ci.Rmd +++ b/pkg_ci.Rmd @@ -60,6 +60,8 @@ Details of how to run tests/checks using different versions of R locally can be You can fine tune the deployment of tests with each versions by using a testing matrix. See this [more complex example](https://github.com/r-hub/rhub/blob/master/.travis.yml#L5) of a Travis configuration where pkgdown documentation is built during the release R version testing only. +For a package depending on Bioconductor packages, or a Bioconductor package, [Travis options allow to test on either Bioconductor release or devel (or both)](https://docs.travis-ci.com/user/languages/r/#bioconductor). + #### Minimizing build times on Travis Please use these tips to minimize build time on Travis especially after your package project gets transferred to ropensci Travis account: