[Genabel-commits] r1717 - www
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Apr 30 10:57:52 CEST 2014
Author: lckarssen
Date: 2014-04-30 10:57:49 +0200 (Wed, 30 Apr 2014)
New Revision: 1717
Added:
www/packageReviewGuidelines.html
www/packageReviewGuidelines.org
Log:
Added a first draft of the GenABEL package review guidelines.
Added: www/packageReviewGuidelines.html
===================================================================
--- www/packageReviewGuidelines.html (rev 0)
+++ www/packageReviewGuidelines.html 2014-04-30 08:57:49 UTC (rev 1717)
@@ -0,0 +1,331 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+<title>GenABEL Project Package Review Guidelines</title>
+<!-- 2014-04-30 wo 10:52 -->
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+<meta name="generator" content="Org-mode" />
+<meta name="author" content="Y. Aulchenko, L.C. Karssen" />
+<style type="text/css">
+ <!--/*--><![CDATA[/*><!--*/
+ .title { text-align: center; }
+ .todo { font-family: monospace; color: red; }
+ .done { color: green; }
+ .tag { background-color: #eee; font-family: monospace;
+ padding: 2px; font-size: 80%; font-weight: normal; }
+ .timestamp { color: #bebebe; }
+ .timestamp-kwd { color: #5f9ea0; }
+ .right { margin-left: auto; margin-right: 0px; text-align: right; }
+ .left { margin-left: 0px; margin-right: auto; text-align: left; }
+ .center { margin-left: auto; margin-right: auto; text-align: center; }
+ .underline { text-decoration: underline; }
+ #postamble p, #preamble p { font-size: 90%; margin: .2em; }
+ p.verse { margin-left: 3%; }
+ pre {
+ border: 1px solid #ccc;
+ box-shadow: 3px 3px 3px #eee;
+ padding: 8pt;
+ font-family: monospace;
+ overflow: auto;
+ margin: 1.2em;
+ }
+ pre.src {
+ position: relative;
+ overflow: visible;
+ padding-top: 1.2em;
+ }
+ pre.src:before {
+ display: none;
+ position: absolute;
+ background-color: white;
+ top: -10px;
+ right: 10px;
+ padding: 3px;
+ border: 1px solid black;
+ }
+ pre.src:hover:before { display: inline;}
+ pre.src-sh:before { content: 'sh'; }
+ pre.src-bash:before { content: 'sh'; }
+ pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
+ pre.src-R:before { content: 'R'; }
+ pre.src-perl:before { content: 'Perl'; }
+ pre.src-java:before { content: 'Java'; }
+ pre.src-sql:before { content: 'SQL'; }
+
+ table { border-collapse:collapse; }
+ td, th { vertical-align:top; }
+ th.right { text-align: center; }
+ th.left { text-align: center; }
+ th.center { text-align: center; }
+ td.right { text-align: right; }
+ td.left { text-align: left; }
+ td.center { text-align: center; }
+ dt { font-weight: bold; }
+ .footpara:nth-child(2) { display: inline; }
+ .footpara { display: block; }
+ .footdef { margin-bottom: 1em; }
+ .figure { padding: 1em; }
+ .figure p { text-align: center; }
+ .inlinetask {
+ padding: 10px;
+ border: 2px solid gray;
+ margin: 10px;
+ background: #ffffcc;
+ }
+ #org-div-home-and-up
+ { text-align: right; font-size: 70%; white-space: nowrap; }
+ textarea { overflow-x: auto; }
+ .linenr { font-size: smaller }
+ .code-highlighted { background-color: #ffff00; }
+ .org-info-js_info-navigation { border-style: none; }
+ #org-info-js_console-label
+ { font-size: 10px; font-weight: bold; white-space: nowrap; }
+ .org-info-js_search-highlight
+ { background-color: #ffff00; color: #000000; font-weight: bold; }
+ /*]]>*/-->
+</style>
+<script type="text/javascript">
+/*
+ at licstart The following is the entire license notice for the
+JavaScript code in this tag.
+
+Copyright (C) 2012-2013 Free Software Foundation, Inc.
+
+The JavaScript code in this tag is free software: you can
+redistribute it and/or modify it under the terms of the GNU
+General Public License (GNU GPL) as published by the Free Software
+Foundation, either version 3 of the License, or (at your option)
+any later version. The code is distributed WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
+
+As additional permission under GNU GPL version 3 section 7, you
+may distribute non-source (e.g., minimized or compacted) forms of
+that code without the copy of the GNU GPL normally required by
+section 4, provided you include this license notice and a URL
+through which recipients can access the Corresponding Source.
+
+
+ at licend The above is the entire license notice
+for the JavaScript code in this tag.
+*/
+<!--/*--><![CDATA[/*><!--*/
+ function CodeHighlightOn(elem, id)
+ {
+ var target = document.getElementById(id);
+ if(null != target) {
+ elem.cacheClassElem = elem.className;
+ elem.cacheClassTarget = target.className;
+ target.className = "code-highlighted";
+ elem.className = "code-highlighted";
+ }
+ }
+ function CodeHighlightOff(elem, id)
+ {
+ var target = document.getElementById(id);
+ if(elem.cacheClassElem)
+ elem.className = elem.cacheClassElem;
+ if(elem.cacheClassTarget)
+ target.className = elem.cacheClassTarget;
+ }
+/*]]>*///-->
+</script>
+</head>
+<body>
+<div id="content">
+<h1 class="title">GenABEL Project Package Review Guidelines</h1>
+<div id="table-of-contents">
+<h2>Table of Contents</h2>
+<div id="text-table-of-contents">
+<ul>
+<li><a href="#sec-1">1. Introduction</a></li>
+<li><a href="#sec-2">2. Legal issues</a>
+<ul>
+<li><a href="#sec-2-1">2.1. Is there a clear (standard) license?</a></li>
+<li><a href="#sec-2-2">2.2. Is the license GNU GPL-compatible?</a></li>
+</ul>
+</li>
+<li><a href="#sec-3">3. Technical quality</a>
+<ul>
+<li><a href="#sec-3-1">3.1. Is the installation procedure clearly documented? Is the code easy to compile and run?</a></li>
+<li><a href="#sec-3-2">3.2. [For R packages] Does the package pass CRAN checks ()? At minimum, run "R CMD check …" and "R CMD check –as-cran …"</a></li>
+<li><a href="#sec-3-3">3.3. Is the package documented? What is the quality of the documentation?</a></li>
+<li><a href="#sec-3-4">3.4. [For R packages] Does <code>help(PackageName)</code> provide an adequate summary of the package and a review of the major functions?</a></li>
+<li><a href="#sec-3-5">3.5. [For R packages] Does the package use Roxygen2 for documentation?</a></li>
+<li><a href="#sec-3-6">3.6. Are examples of usage provided?</a></li>
+<li><a href="#sec-3-7">3.7. Does the package provide a tutorial/vignette? Can you comment on the tutorial?</a></li>
+<li><a href="#sec-3-8">3.8. Is the source code of the tutorial/vignette provided?</a></li>
+<li><a href="#sec-3-9">3.9. Does the package make use of unit/integration/etc. tests?</a></li>
+<li><a href="#sec-3-10">3.10. [For R packages] Does the package make use of RUnit testing?</a></li>
+<li><a href="#sec-3-11">3.11. Does the code comply with the GenABEL coding standards?</a></li>
+<li><a href="#sec-3-12">3.12. Is the code readable/understandable?</a></li>
+<li><a href="#sec-3-13">3.13. Does the code contain explanatory comments?</a></li>
+<li><a href="#sec-3-14">3.14. Were the design and methods implemented in package discussed during the development process (e.g. on the genabel-devel mailing list)?</a></li>
+</ul>
+</li>
+<li><a href="#sec-4">4. Content</a>
+<ul>
+<li><a href="#sec-4-1">4.1. Does the package address the problem in the domain of statistical genomics?</a></li>
+<li><a href="#sec-4-2">4.2. Is it streamlining analyses not covered elsewhere in the GenABEL suite? If not, does it improve the analysis already covered?</a></li>
+<li><a href="#sec-4-3">4.3. Should it become a separate package or rather be incorporated into an existing package?</a></li>
+<li><a href="#sec-4-4">4.4. Are any of the data types defined in other GenABEL packages used?</a></li>
+<li><a href="#sec-4-5">4.5. Are code/functions/data defined in other GenABEL packages used?</a></li>
+</ul>
+</li>
+<li><a href="#sec-5">5. Suggestions</a>
+<ul>
+<li><a href="#sec-5-1">5.1. What are the major issues which should be addressed?</a></li>
+<li><a href="#sec-5-2">5.2. What other (optional) suggestions you could make to the author?</a></li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+
+<div id="outline-container-sec-1" class="outline-2">
+<h2 id="sec-1"><span class="section-number-2">1</span> Introduction</h2>
+<div class="outline-text-2" id="text-1">
+<p>
+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.
+</p>
+
+<p>
+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:
+</p>
+<ul class="org-ul">
+<li><i>Maintainability of the package</i>: is the code understandable? Does
+it follow <a href="codingstyle.html">our coding standards</a>? Is the code documented?
+</li>
+<li><i>User-friendliness</i>: What is the quality of the user
+documentation? Are there any examples? Is the user interface
+compatible with what is to be expected?
+</li>
+</ul>
+
+<p>
+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.
+</p>
+
+<p>
+<b>Please consider this document a working draft</b>. Feedback is very much
+welcomed.
+</p>
+
+<p>
+Note that our coding style closely follows the Google style guide and
+is documented at <a href="codingstyle.html">here</a>.
+</p>
+</div>
+</div>
+<div id="outline-container-sec-2" class="outline-2">
+<h2 id="sec-2"><span class="section-number-2">2</span> Legal issues</h2>
+<div class="outline-text-2" id="text-2">
+</div><div id="outline-container-sec-2-1" class="outline-3">
+<h3 id="sec-2-1"><span class="section-number-3">2.1</span> Is there a clear (standard) license?</h3>
+</div>
+<div id="outline-container-sec-2-2" class="outline-3">
+<h3 id="sec-2-2"><span class="section-number-3">2.2</span> Is the license GNU GPL-compatible?</h3>
+</div>
+</div>
+
+<div id="outline-container-sec-3" class="outline-2">
+<h2 id="sec-3"><span class="section-number-2">3</span> Technical quality</h2>
+<div class="outline-text-2" id="text-3">
+</div><div id="outline-container-sec-3-1" class="outline-3">
+<h3 id="sec-3-1"><span class="section-number-3">3.1</span> Is the installation procedure clearly documented? Is the code easy to compile and run?</h3>
+</div>
+<div id="outline-container-sec-3-2" class="outline-3">
+<h3 id="sec-3-2"><span class="section-number-3">3.2</span> [For R packages] Does the package pass CRAN checks (<a href="http://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Checking-packages">http://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Checking-packages</a>)? At minimum, run "R CMD check …" and "R CMD check –as-cran …"</h3>
+</div>
+<div id="outline-container-sec-3-3" class="outline-3">
+<h3 id="sec-3-3"><span class="section-number-3">3.3</span> Is the package documented? What is the quality of the documentation?</h3>
+</div>
+<div id="outline-container-sec-3-4" class="outline-3">
+<h3 id="sec-3-4"><span class="section-number-3">3.4</span> [For R packages] Does <code>help(PackageName)</code> provide an adequate summary of the package and a review of the major functions?</h3>
+</div>
+<div id="outline-container-sec-3-5" class="outline-3">
+<h3 id="sec-3-5"><span class="section-number-3">3.5</span> [For R packages] Does the package use Roxygen2 for documentation?</h3>
+</div>
+<div id="outline-container-sec-3-6" class="outline-3">
+<h3 id="sec-3-6"><span class="section-number-3">3.6</span> Are examples of usage provided?</h3>
+</div>
+<div id="outline-container-sec-3-7" class="outline-3">
+<h3 id="sec-3-7"><span class="section-number-3">3.7</span> Does the package provide a tutorial/vignette? Can you comment on the tutorial?</h3>
+</div>
+<div id="outline-container-sec-3-8" class="outline-3">
+<h3 id="sec-3-8"><span class="section-number-3">3.8</span> Is the source code of the tutorial/vignette provided?</h3>
+</div>
+<div id="outline-container-sec-3-9" class="outline-3">
+<h3 id="sec-3-9"><span class="section-number-3">3.9</span> Does the package make use of unit/integration/etc. tests?</h3>
+</div>
+<div id="outline-container-sec-3-10" class="outline-3">
+<h3 id="sec-3-10"><span class="section-number-3">3.10</span> [For R packages] Does the package make use of RUnit testing?</h3>
+</div>
+<div id="outline-container-sec-3-11" class="outline-3">
+<h3 id="sec-3-11"><span class="section-number-3">3.11</span> Does the code comply with the <a href="codingstyle.html">GenABEL coding standards</a>?</h3>
+</div>
+<div id="outline-container-sec-3-12" class="outline-3">
+<h3 id="sec-3-12"><span class="section-number-3">3.12</span> Is the code readable/understandable?</h3>
+</div>
+<div id="outline-container-sec-3-13" class="outline-3">
+<h3 id="sec-3-13"><span class="section-number-3">3.13</span> Does the code contain explanatory comments?</h3>
+</div>
+<div id="outline-container-sec-3-14" class="outline-3">
+<h3 id="sec-3-14"><span class="section-number-3">3.14</span> Were the design and methods implemented in package discussed during the development process (e.g. on the genabel-devel mailing list)?</h3>
+</div>
+</div>
+
+<div id="outline-container-sec-4" class="outline-2">
+<h2 id="sec-4"><span class="section-number-2">4</span> Content</h2>
+<div class="outline-text-2" id="text-4">
+</div><div id="outline-container-sec-4-1" class="outline-3">
+<h3 id="sec-4-1"><span class="section-number-3">4.1</span> Does the package address the problem in the domain of statistical genomics?</h3>
+</div>
+<div id="outline-container-sec-4-2" class="outline-3">
+<h3 id="sec-4-2"><span class="section-number-3">4.2</span> Is it streamlining analyses not covered elsewhere in the GenABEL suite? If not, does it improve the analysis already covered?</h3>
+</div>
+<div id="outline-container-sec-4-3" class="outline-3">
+<h3 id="sec-4-3"><span class="section-number-3">4.3</span> Should it become a separate package or rather be incorporated into an existing package?</h3>
+</div>
+<div id="outline-container-sec-4-4" class="outline-3">
+<h3 id="sec-4-4"><span class="section-number-3">4.4</span> Are any of the data types defined in other GenABEL packages used?</h3>
+</div>
+<div id="outline-container-sec-4-5" class="outline-3">
+<h3 id="sec-4-5"><span class="section-number-3">4.5</span> Are code/functions/data defined in other GenABEL packages used?</h3>
+</div>
+</div>
+
+<div id="outline-container-sec-5" class="outline-2">
+<h2 id="sec-5"><span class="section-number-2">5</span> Suggestions</h2>
+<div class="outline-text-2" id="text-5">
+</div><div id="outline-container-sec-5-1" class="outline-3">
+<h3 id="sec-5-1"><span class="section-number-3">5.1</span> What are the major issues which should be addressed?</h3>
+</div>
+<div id="outline-container-sec-5-2" class="outline-3">
+<h3 id="sec-5-2"><span class="section-number-3">5.2</span> What other (optional) suggestions you could make to the author?</h3>
+</div>
+</div>
+</div>
+<div id="postamble" class="status">
+<p class="date">Date: <span class="timestamp-wrapper"><span class="timestamp"><2014-04-26 za></span></span></p>
+<p class="author">Author: Y. Aulchenko, L.C. Karssen</p>
+<p class="date">Created: 2014-04-30 wo 10:52</p>
+<p class="creator">Emacs 24.3.1 (Org mode 8.2.4)</p>
+<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
+</div>
+</body>
+</html>
Added: www/packageReviewGuidelines.org
===================================================================
--- www/packageReviewGuidelines.org (rev 0)
+++ www/packageReviewGuidelines.org 2014-04-30 08:57:49 UTC (rev 1717)
@@ -0,0 +1,72 @@
+#+TITLE: GenABEL Project Package Review Guidelines
+#+DATE: <2014-04-26 za>
+#+AUTHOR: Y. Aulchenko, L.C. Karssen
+#+EMAIL: l.c.karssen at gmail.com
+#+OPTIONS: ':nil *:t -:t ::t <:t H:3 \n:nil ^:t arch:headline
+#+OPTIONS: author:t c:nil creator:comment d:(not "LOGBOOK") date:t
+#+OPTIONS: e:t email:nil f:t inline:t num:t p:nil pri:t stat:t tags:t
+#+OPTIONS: tasks:t tex:t timestamp:t toc:t todo:t |:t
+#+CREATOR: Emacs 24.3.1 (Org mode 8.2.4)
+#+DESCRIPTION:
+#+EXCLUDE_TAGS: noexport
+#+KEYWORDS:
+#+LANGUAGE: en
+#+SELECT_TAGS: export
+
+* 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 [[file:codingstyle.html][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 at [[file:codingstyle.html][here]].
+
+* Legal issues
+** Is there a clear (standard) license?
+** Is the license GNU GPL-compatible?
+* Technical quality
+** Is the installation procedure clearly documented? Is the code easy to compile and run?
+** [For R packages] Does the package pass CRAN checks (http://cran.r-project.org/doc/manuals/r-devel/R-exts.html#Checking-packages)? At minimum, run "R CMD check ..." and "R CMD check --as-cran ..."
+** Is the package documented? What is the quality of the documentation?
+** [For R packages] Does =help(PackageName)= provide an adequate summary of the package and a review of the major functions?
+** [For R packages] Does the package use Roxygen2 for documentation?
+** Are examples of usage provided?
+** Does the package provide a tutorial/vignette? Can you comment on the tutorial?
+** Is the source code of the tutorial/vignette provided?
+** Does the package make use of unit/integration/etc. tests?
+** [For R packages] Does the package make use of RUnit testing?
+** Does the code comply with the [[file:codingstyle.html][GenABEL coding standards]]?
+** Is the code readable/understandable?
+** Does the code contain explanatory comments?
+** Were the design and methods implemented in package discussed during the development process (e.g. on the genabel-devel mailing list)?
+* Content
+** Does the package address the problem in the domain of statistical genomics?
+** Is it streamlining analyses not covered elsewhere in the GenABEL suite? If not, does it improve the analysis already covered?
+** Should it become a separate package or rather be incorporated into an existing package?
+** Are any of the data types defined in other GenABEL packages used?
+** Are code/functions/data defined in other GenABEL packages used?
+* Suggestions
+** What are the major issues which should be addressed?
+** What other (optional) suggestions you could make to the author?
More information about the Genabel-commits
mailing list