mirror of
https://github.com/apache/commons-math.git
synced 2025-02-07 02:29:20 +00:00
772d74b0fb
Adding documentation for Contributors. Adding xsl stylesheets to render xdoc in browser and css to style content, this makes testing documentation additions easier without rendering the entire site. Simply open up xdoc in browser to see what it will look like after rendering. git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/math/trunk@141018 13f79535-47bb-0310-9956-ffa450edef68
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>
|