commons-math/xdocs/developers.xml

263 lines
13 KiB
XML

<?xml version="1.0"?>
<!--
Copyright 2003-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<?xml-stylesheet type="text/xsl" href="xdoc.xsl"?>
<!-- $Revision$ $Date$ -->
<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>
Here are some steps to take to get starting contributing to commons-math:
</p>
<p>
<ol>
<li>Start by reviewing the overall objectives stated in the
<a href="proposal.html">proposal</a> upon which the project is
founded.
</li>
<li>Download the commons math source code. Follow the instructions
under the heading "Anonymous Subversion"
<a href="http://www.apache.org/dev/version-control.html">here</a> (and
also have a look <a href="http://wiki.apache.org/jakarta-commons/UsingSVN">
here</a>) to check out the commons math code base from Subversion
(Jakarta Commons now uses Subversion as our source control system). The
svn url for the current development sources of commons-math
is
<source>https://svn.apache.org/repos/asf/jakarta/commons/proper/math/trunk</source>
</li>
<li>Have a look at the new features that users and developers have requested
on the <a href="http://wiki.apache.org/jakarta-commons/MathWishList">
Math Wish List Wiki Page.</a>
</li>
<li>Be sure to join the commons-dev and commons-user
<a href="mail-lists.html">
email lists</a> and use them appropriately (make sure the string
"[math]" starts the Subject line of all your postings).
Make any proposals here where the group can comment on them.
</li>
<li>
<a href="http://issues.apache.org/bugzilla/createaccount.cgi">
Setup an account on Bugzilla</a> and use it to submit patches and
identify bugs. Read the
<a href="http://issues.apache.org/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://issues.apache.org/bugzilla/enter_bug.cgi?reporter=&amp;product=Commons&amp;version=unspecified&amp;component=Math&amp;rep_platform=All&amp;op_sys=All&amp;priority=Other&amp;bug_severity=normal&amp;bug_status=NEW&amp;assigned_to=&amp;cc=&amp;bug_file_loc=&amp;short_desc=%5Bmath%5D%5Bpatch%5D+%22Your+subject+heading+here%22&amp;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.&amp;maketemplate=Remember+values+as+bookmarkable+template&amp;form_name=enter_bug">
Bookmarkable Template for submitting patches.
</a></li>
<li><a href="http://issues.apache.org/bugzilla/enter_bug.cgi?reporter=&amp;product=Commons&amp;version=unspecified&amp;component=Math&amp;rep_platform=All&amp;op_sys=All&amp;priority=Other&amp;bug_severity=normal&amp;bug_status=NEW&amp;assigned_to=&amp;cc=&amp;bug_file_loc=http%3A%2F%2F&amp;short_desc=%5Bmath%5D+%22Your+subject+heading+here%22&amp;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.&amp;maketemplate=Remember+values+as+bookmarkable+template&amp;form_name=enter_bug">
Bookmarkable Template for submitting bugs.
</a></li>
</ul>
<p>
Querying the Database:
</p>
<ul>
<li><a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;email1=&amp;emailtype1=substring&amp;emailassigned_to1=1&amp;email2=&amp;emailtype2=substring&amp;emailreporter2=1&amp;bugidtype=include&amp;bug_id=&amp;changedin=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;product=Commons&amp;component=Math&amp;short_desc=&amp;short_desc_type=allwordssubstr&amp;long_desc=&amp;long_desc_type=allwordssubstr&amp;bug_file_loc=&amp;bug_file_loc_type=allwordssubstr&amp;keywords=&amp;keywords_type=anywords&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=&amp;cmdtype=doit&amp;newqueryname=&amp;order=Reuse+same+sort+as+last+time">
New and Existing Issues.
</a></li>
<li><a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=RESOLVED&amp;bug_status=VERIFIED&amp;bug_status=CLOSED&amp;email1=&amp;emailtype1=substring&amp;emailassigned_to1=1&amp;email2=&amp;emailtype2=substring&amp;emailreporter2=1&amp;bugidtype=include&amp;bug_id=&amp;changedin=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;product=Commons&amp;component=Math&amp;short_desc=&amp;short_desc_type=allwordssubstr&amp;long_desc=&amp;long_desc_type=allwordssubstr&amp;bug_file_loc=&amp;bug_file_loc_type=allwordssubstr&amp;keywords=&amp;keywords_type=anywords&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=&amp;cmdtype=doit&amp;newqueryname=&amp;order=Reuse+same+sort+as+last+time">
Resolved and Closed Issues.
</a></li>
</ul>
<li>
Generating patches: The requested format for generating patches is the Unified Diff format,
which can be easily generated using the svn client or Eclipse IDE.
<source>svn diff > patch </source>
</li>
</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.xml</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>
External references or full statements of definitions for all mathematical
terms used in component documentation <i>must</i> be provided.</li>
<li>
Implementations <i>should</i> use standard algorithms and
references or full descriptions of all algorithms <i>should</i> be
provided.</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 Apache
<a href="http://www.apache.org/licenses/cla.pdf">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.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/>
</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>