GenABEL Project Package Review Guidelines
Table of Contents
- 1. Introduction
- 2. Legal issues
- 3. Technical quality
- 3.1. Is the installation procedure clearly documented? Is the code easy to compile and run?
- 3.2. [For R packages] Does the package pass CRAN checks ()? At minimum, run "R CMD check …" and "R CMD check –as-cran …"
- 3.3. Is the package documented? What is the quality of the documentation?
- 3.4. [For R packages] Does
help(PackageName)provide an adequate summary of the package and a review of the major functions? - 3.5. [For R packages] Does the package use Roxygen2 for documentation?
- 3.6. Are examples of usage provided?
- 3.7. Does the package provide a tutorial/vignette? Can you comment on the tutorial?
- 3.8. Is the source code of the tutorial/vignette provided?
- 3.9. Does the package make use of unit/integration/etc. tests?
- 3.10. [For R packages] Does the package make use of unit tests (e.g. RUnit or testthat)?
- 3.11. Does the code comply with the GenABEL coding standards?
- 3.12. Is the code readable/understandable?
- 3.13. Does the code contain explanatory comments?
- 3.14. Were the design and methods implemented in package discussed during the development process (e.g. on the genabel-devel mailing list)?
- 4. Content
- 4.1. Does the package address a problem in the domain of statistical genomics?
- 4.2. Is it streamlining analyses not covered elsewhere in the GenABEL suite? If not, does it improve the analysis already covered?
- 4.3. Should it become a separate package or rather be incorporated into an existing package?
- 4.4. Does the package use any of the data types defined in other GenABEL packages?
- 4.5. Does the package use code/functions/data defined in other GenABEL packages?
- 5. Recommendations
1 Introduction
One of the goals of the GenABEL project is to be an environment in which people can work on the implementation of statistical methodology into user-friendly software packages.
In order for the project to be sustainable the packages that are accepted into the GenABEL suite must meet certain standards. Without certain standards/guidelines package maintenance will be difficult and time consuming. Moreover, if the user interface is awkward of if the package lacks documentation users will be less likely to use the package. In short these standard revolve around the following:
- Maintainability of the package: is the code understandable? Does it follow our coding standards? Is the code documented?
- User-friendliness: What is the quality of the user documentation? Are there any examples? Is the user interface compatible with what is to be expected?
One of the ways to ensure a healthy ecosystem is to have reviews of candidate packages. Such a review would be similar to the peer review done for scientific publications. In order to have good quality package reviews we have put together this document describing in a structured way the minimum questions a package reviewer should ask.
Please consider this document a working draft. Feedback is very much welcomed.
Note that our coding style closely follows the Google style guide and is documented here.
2 Legal issues
2.1 Is the copyright holder clearly mentioned?
2.2 Is there a clear (standard) license?
If yes:
- is it on the list of licences accepted by CRAN (https://svn.r-project.org/R/trunk/share/licenses/license.db)?
- is it on the list of GPL compatible licences (http://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses)? This is optional to package acceptance.