| <?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=&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=%5Bmath%5D%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://issues.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=%5Bmath%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://issues.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://issues.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> |
| 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> |
