322 lines
16 KiB
XML
322 lines
16 KiB
XML
<?xml version="1.0"?>
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You 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><strong>Getting Started</strong></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" on the
|
|
<a href="http://www.apache.org/dev/version-control.html">Apache version
|
|
control page</a> (Also have a look at the
|
|
<a href="http://wiki.apache.org/commons/UsingSVN">Commons wiki
|
|
svn page </a>) to check out the commons math code base from Subversion.
|
|
The svn url for the current development sources of commons-math
|
|
is
|
|
<source>https://svn.apache.org/repos/asf/commons/proper/math/trunk</source>
|
|
</li>
|
|
<li>Like most commons components, commons-math uses maven as our build
|
|
tool. Follow the
|
|
<a href="http://commons.apache.org/building.html">building
|
|
components</a> instructions to get set up with maven so that you
|
|
can build commons-math from source.
|
|
</li>
|
|
<li>Have a look at the new features that users and developers have requested
|
|
on the <a href="http://wiki.apache.org/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>
|
|
<p><strong>Contributing ideas and code</strong></p>
|
|
<p>
|
|
Follow the steps below when making suggestions for additions or
|
|
enhancements to commons-math. This will make it easier for the community
|
|
to comment on your ideas and for the committers to keep track of them.
|
|
Thanks in advance!
|
|
<ol>
|
|
<li>Start with a post to the commons-dev mailing list, with [math] at
|
|
the beginning of the subject line, followed by a good, short title
|
|
describing the new feature or enhancement. For example, "[math]
|
|
Prinicpal Components Analysis." The body of the post should include each
|
|
of the following items (but be <strong>as brief as possible</strong>):
|
|
<ul>
|
|
<li>A concise description of the new feature / enhancement</li>
|
|
<li>References to definitions and algorithms. Using standard
|
|
definitions and algorithms makes communication much easier and will
|
|
greatly increase the chances that we will accept the code / idea</li>
|
|
<li>Some indication of why the addition / enhancement is practically
|
|
useful</li>
|
|
</ul></li>
|
|
<li>Assuming a generally favorable response to the idea on commons-dev,
|
|
the next step is to add an entry to the
|
|
<a href="http://wiki.apache.org/commons/MathWishList">Math Wish
|
|
List</a> corresponding to the idea. Include a reference to the
|
|
discussion thread and, for substantial enhancements, a new Wiki page
|
|
named using the enhancement / addition name, e.g.
|
|
"PrincipalComponentsAnalysis." We can then us this page to lay out the
|
|
development plan and track progress and decisions related to the
|
|
feature.</li>
|
|
<li>Create a Bugzilla ticket using the the feature title as the short
|
|
description. Incorporate feedback from the initial posting in the
|
|
description. Add a link to the Bugzilla ticket to the WishList entry.
|
|
</li>
|
|
<li>Submit code as attachments to the Bugzilla ticket. Please use one
|
|
ticket for each feature, adding multiple patches to the ticket
|
|
as necessary. Use the svn diff command to generate your patches as
|
|
diffs. Please do not submit modified copies of existing java files. Be
|
|
patient (but not <strong>too</strong> patient) with committers reviewing
|
|
patches. Post a *nudge* message to commons-dev with a reference to the
|
|
ticket if a patch goes more than a few days with no comment or commit.
|
|
</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. One thing
|
|
that Checkstyle will complain about is tabs included in the source code.
|
|
Please make sure to set your IDE or editor to use spaces instead of tabs.
|
|
</p>
|
|
<p>
|
|
Committers should make sure that svn properties are correctly set on
|
|
files added to the repository. See the section on Committer Subversion
|
|
Access on the <a href="http://www.apache.org/dev/version-control.html">
|
|
Apache Source Code Repositories</a> page.
|
|
</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>
|
|
<li>
|
|
Additions and enhancements <i>should</i> include updates to the User
|
|
Guide.</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. In particular, contributions should not
|
|
implement or include references to algorithms in
|
|
<a href="http://www.nr.com/">Numerical Recipes (NR)</a>.
|
|
Any questions about copyright or patent issues should be raised on
|
|
the commons-dev mailing list before contributing or committing code.
|
|
</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.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>
|