243 lines
12 KiB
XML
243 lines
12 KiB
XML
<?xml version="1.0"?>
|
|
<?xml-stylesheet type="text/xsl" href="xdoc.xsl"?>
|
|
<!-- $Revision: 1.9 $ $Date: 2003/11/15 18:38:16 $ -->
|
|
<document>
|
|
<properties>
|
|
<title>Developers Guide</title>
|
|
<author email="rdonkin@apache.org">Robert Burrell Donkin</author>
|
|
</properties>
|
|
|
|
<body>
|
|
<section name="Aims">
|
|
<p>
|
|
Creating and maintaining a mathematical and statistical library that is
|
|
accurate requires a greater degree of communication than might be the
|
|
case for other components. It is important that developers follow
|
|
guidelines laid down by the community to ensure that the code they create
|
|
can be successfully maintained by others.
|
|
</p>
|
|
</section>
|
|
<section name='Guidelines'>
|
|
<p>
|
|
Developers are asked to comply with the following development guidelines.
|
|
Code that does not comply with the guidelines including the word <i>must</i>
|
|
will not be committed. Our aim will be to fix all of the exceptions to the
|
|
"<i>should</i>" guidelines prior to a release.
|
|
</p>
|
|
<subsection name="Contributing">
|
|
<p>
|
|
Becoming involved with a community project such as Commons Math can at
|
|
first appear to be very daunting. The Math projects motivations are to
|
|
design and build a well thoughtout API. With this in mind, there is a great
|
|
deal of review and discussion revolving around how and why a particular
|
|
package is included or written into the project. It is understandable that
|
|
individuals may have an interest in donating either their time or code to the
|
|
project, and we want to promote this. For this reason, we are working to
|
|
maintain guidelines for proposing additional packages or coding efforts
|
|
within the project.
|
|
</p>
|
|
<p>
|
|
<ol>
|
|
<li>Formost it is important to review the overall objectives
|
|
and <a href="proposal.html">proposal</a> upon which the project is
|
|
founded.
|
|
</li>
|
|
<li>Review the completed, current and future
|
|
<a href="tasks.html">tasks</a> of the project.
|
|
</li>
|
|
<li>Be sure to join the Commons Developer and Interest <a href="mail-lists.html">
|
|
email lists</a> and use them appropriately (make sure the string "[math]" is
|
|
somewhere in the Subject line of all your postings). Make any proposals here
|
|
where the group can comment on them
|
|
</li>
|
|
<li>
|
|
<a href="http://nagoya.apache.org/bugzilla/createaccount.cgi">Setup an account on Bugzilla</a>
|
|
and use it to formally submit Patches and identify bugs. Read the
|
|
<a href="http://nagoya.apache.org/bugzilla/bugwritinghelp.html">directions</a> for
|
|
submitting bugs and search the database to determine if an issue exists or has
|
|
already been dealt with.
|
|
|
|
<p>
|
|
Submitting Issues:
|
|
</p>
|
|
<ul>
|
|
<li><a href="http://nagoya.apache.org/bugzilla/enter_bug.cgi?reporter=&product=Commons&version=unspecified&component=Math&rep_platform=All&op_sys=All&priority=Other&bug_severity=normal&bug_status=NEW&assigned_to=&cc=&bug_file_loc=&short_desc=%5Bpatch%5D+%22Your+subject+heading+here%22&comment=Please+provide+details+here.+Its+best+to+submit+patches+that+alter+existing+file%0D%0Acontent+in+%22unified+cvs+diff%22+format.+%0D%0A%0D%0ASubmissions+that+provide+new+files+can+be+supplied+as+direct+file+attachments+or%0D%0Aarchives+in+zip+or+tar.gz+format.+please+be+kind+enough+to+identify+the+format%0D%0Aof+the+attached+archive+as+bugzill+tends+to+strip+these+characterstics+by%0D%0Aremoving+the+files+extension.&maketemplate=Remember+values+as+bookmarkable+template&form_name=enter_bug">
|
|
Bookmarkable Template for submitting patches.
|
|
</a></li>
|
|
<li><a href="http://nagoya.apache.org/bugzilla/enter_bug.cgi?reporter=&product=Commons&version=unspecified&component=Math&rep_platform=All&op_sys=All&priority=Other&bug_severity=normal&bug_status=NEW&assigned_to=&cc=&bug_file_loc=http%3A%2F%2F&short_desc=%5Bbug+report%5D+%22Your+subject+heading+here%22&comment=Please+review+the+bug+writing+guidelines+and+supply+as+much+detail+as+possible%0D%0Ato+allow+us+to+diagnose+and+correct+the+existing+issue.+Please+search+the+bug%0D%0Adatabase+to+determine+if+the+bug+has+possibly+been+addressed+in+the+past.&maketemplate=Remember+values+as+bookmarkable+template&form_name=enter_bug">
|
|
Bookmarkable Template for submitting bugs.
|
|
</a></li>
|
|
</ul>
|
|
|
|
<p>
|
|
Querying the Database:
|
|
</p>
|
|
<ul>
|
|
<li><a href="http://nagoya.apache.org/bugzilla/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&bugidtype=include&bug_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&product=Commons&component=Math&short_desc=&short_desc_type=allwordssubstr&long_desc=&long_desc_type=allwordssubstr&bug_file_loc=&bug_file_loc_type=allwordssubstr&keywords=&keywords_type=anywords&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&newqueryname=&order=Reuse+same+sort+as+last+time">
|
|
New and Existing Issues.
|
|
</a></li>
|
|
<li><a href="http://nagoya.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&bugidtype=include&bug_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&product=Commons&component=Math&short_desc=&short_desc_type=allwordssubstr&long_desc=&long_desc_type=allwordssubstr&bug_file_loc=&bug_file_loc_type=allwordssubstr&keywords=&keywords_type=anywords&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&newqueryname=&order=Reuse+same+sort+as+last+time">
|
|
Resolved and Closed Issues.
|
|
</a></li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
</p>
|
|
</subsection>
|
|
<subsection name='Coding Style'>
|
|
<p>
|
|
Commons-math follows <a href="http://java.sun.com/docs/codeconv/">Code
|
|
Conventions for the Java Programming Language</a>. As part of the maven
|
|
build process, style checking is performed using the checkStyle plugin,
|
|
using the properties specified in <code>checkStyle.properties</code>.
|
|
Committed code <i>should</i> generate no checkStyle errors.
|
|
</p>
|
|
</subsection>
|
|
<subsection name='Documentation'>
|
|
<ul>
|
|
<li>
|
|
Committed code <i>must</i> include full javadoc.</li>
|
|
<li>
|
|
All component contracts <i>must</i> be fully specified in the javadoc class,
|
|
interface or method comments, including specification of acceptable ranges
|
|
of values, exceptions or special return values.</li>
|
|
<li>
|
|
References to definitions for all mathematical
|
|
terms used in component documentation <i>must</i> be provided, preferably
|
|
as HTML links.</li>
|
|
<li>
|
|
Implementations <i>should</i> use standard algorithms and
|
|
references to algorithm descriptions <i>should</i> be provided,
|
|
preferably as HTML links.</li>
|
|
</ul>
|
|
</subsection>
|
|
<subsection name='Unit Tests'>
|
|
<ul>
|
|
<li>
|
|
Committed code <i>must</i> include unit tests.</li>
|
|
<li>
|
|
Unit tests <i>should</i> provide full path coverage. </li>
|
|
<li>
|
|
Unit tests <i>should</i> verify all boundary conditions specified in
|
|
interface contracts, including verification that exceptions are thrown or
|
|
special values (e.g. Double.NaN, Double.Infinity) are returned as
|
|
expected. </li>
|
|
</ul>
|
|
</subsection>
|
|
<subsection name='Licensing and copyright'>
|
|
<ul>
|
|
<li>
|
|
All new source file submissions <i>must</i> include the Apache Software
|
|
License in a comment that begins the file </li>
|
|
<li>
|
|
All contributions must comply with the terms of the
|
|
<a href="http://www.apache.org/foundation/ASF_Contributor_License_1_form.pdf">
|
|
Apache Contributor License Agreement (CLA)</a></li>
|
|
<li>
|
|
Patches <i>must</i> be accompanied by a clear reference to a "source"
|
|
- if code has been "ported" from another language, clearly state the
|
|
source of the original implementation. If the "expression" of a given
|
|
algorithm is derivative, please note the original source (textbook,
|
|
paper, etc.).</li>
|
|
<li>
|
|
References to source materials covered by restrictive proprietary
|
|
licenses should be avoided.</li>
|
|
</ul>
|
|
</subsection>
|
|
</section>
|
|
<section name='Recommended Readings'>
|
|
<p>
|
|
Here is a list of relevant materials. Much of the discussion surrounding
|
|
the development of this component will refer to the various sources
|
|
listed below, and frequently the Javadoc for a particular class or
|
|
interface will link to a definition contained in these documents.
|
|
</p>
|
|
<subsection name='Recommended Readings'>
|
|
<dl>
|
|
<dt>Concerning floating point arithmetic.</dt>
|
|
<dd>
|
|
<a href="http://www.validlab.com/goldberg/paper.ps">
|
|
http://www.validlab.com/goldberg/paper.ps
|
|
</a><br/>
|
|
<a href="http://www.cs.berkeley.edu/~wkahan/ieee754status/ieee754.ps">
|
|
http://www.cs.berkeley.edu/~wkahan/ieee754status/ieee754.ps
|
|
</a><br/>
|
|
<a href="http://www.cs.berkeley.edu/~wkahan/JAVAhurt.pdf">
|
|
http://www.cs.berkeley.edu/~wkahan/JAVAhurt.pdf
|
|
</a><br/>
|
|
</dd>
|
|
<dt>Numerical analysis</dt>
|
|
<dd>
|
|
<a href="http://www.nr.com/">
|
|
Numerical Recipes (NR)
|
|
</a><br/>
|
|
<a href="http://www.mathcom.com/corpdir/techinfo.mdir/scifaq/index.html">
|
|
Scientific Computing FAQ @ Mathcom
|
|
</a><br/>
|
|
<a href="http://www.ma.man.ac.uk/~higham/asna/asna2.pdf">
|
|
Bibliography of accuracy and stability of numerical algorithms
|
|
</a><br/>
|
|
<a href="http://tonic.physics.sunysb.edu/docs/num_meth.html">
|
|
SUNY Stony Brook numerical methods page
|
|
</a><br/>
|
|
<a href="http://epubs.siam.org/sam-bin/dbq/toclist/SINUM">
|
|
SIAM Journal of Numerical Analysis Online
|
|
</a><br/>
|
|
</dd>
|
|
<dt>Probability and statistics</dt>
|
|
<dd>
|
|
<a href="http://lib.stat.cmu.edu/">
|
|
Statlib at CMU
|
|
</a><br/>
|
|
<a href="http://www.itl.nist.gov/div898/handbook/">
|
|
NIST Engineering Statistics Handbook
|
|
</a><br/>
|
|
<a href="http://www.psychstat.smsu.edu/sbk00.htm">
|
|
Online Introductory Statistics (David W. Stockburger)
|
|
</a><br/>
|
|
<a href="http://www.ubmail.ubalt.edu/~harsham/statistics/REFSTAT.HTM">
|
|
Probablility and Statistics Resources
|
|
</a><br/>
|
|
<a href="http://www.jstatsoft.org/">
|
|
Online Journal of Statistical Software
|
|
</a><br/>
|
|
</dd>
|
|
</dl>
|
|
</subsection>
|
|
<subsection name='Javadoc comment resources'>
|
|
<dl>
|
|
<dt>References for mathematical definitions.</dt>
|
|
<dd>
|
|
<a href="http://rd11.web.cern.ch/RD11/rkb/titleA.html">
|
|
http://rd11.web.cern.ch/RD11/rkb/titleA.html
|
|
</a><br/>
|
|
<a href="http://mathworld.wolfram.com/">
|
|
http://mathworld.wolfram.com/
|
|
</a><br/>
|
|
<a href="http://www.itl.nist.gov/div898/handbook">
|
|
http://www.itl.nist.gov/div898/handbook
|
|
</a><br/>
|
|
<a href="http://doi.acm.org/10.1145/359146.359152">
|
|
Chan, T. F. and J. G. Lewis 1979, <i>Communications of the ACM</i>,
|
|
vol. 22 no. 9, pp. 526-531.
|
|
</a><br/>
|
|
<a href="http://www.itl.nist.gov/div898/handbook">
|
|
http://www.wikipedia.org/wiki/
|
|
</a><br/>
|
|
</dd>
|
|
</dl>
|
|
</subsection>
|
|
<subsection name='XML'>
|
|
<dl>
|
|
<dt>XML related resources.</dt>
|
|
<dd>
|
|
<a href="http://www.openmath.org">
|
|
http://www.openmath.org
|
|
</a><br/>
|
|
</dd>
|
|
</dl>
|
|
</subsection>
|
|
</section>
|
|
</body>
|
|
</document>
|