src/site/xdoc/developers.xml - commons-math - Git at Google

 <?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.
   -->

 <!-- $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 Apache Maven as our
             build tool. We now use Maven 2 as our primary build platform (what
             we use to cut releases, for continuous integration builds, and for
             development).  The sources can also be built using Ant (a working
             Ant build.xml is included in the top level project directory).
             To build commons math using Maven 2, you can follow the instructions for
             <a href="http://maven.apache.org/run-maven/index.html">Building a
             project with Maven 2</a>. Launch Maven from the top-level directory
             in the checkout of commons-math trunk. No special setup is required,
             except that currently to build the site (i.e. to execute Maven's
             "site" goal), you may need to increase the default memory allocation
             (e.g. <code>export MAVEN_OPTS=-Xmx512m</code>) before launching
             Maven.
         </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="https://issues.apache.org/jira/secure/Signup!default.jspa">
             Setup an account on JIRA</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>
               See the <a href="http://commons.apache.org/math/issue-tracking.html">
               Commons Math Issue Tracking Page</a> for more information on how to
               search for or submit bugs or enhancement requests.
             </p>
         <li>
           Generating patches: The requested format for generating patches is
           the Unified Diff format, which can be easily generated using the svn
           client or various IDEs.
 <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]
        Principal 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 JIRA ticket using the the feature title as the short
        description. Incorporate feedback from the initial posting in the
        description. Add a reference to the JIRA ticket to the WishList entry.
        </li>
        <li>Submit code as attachments to the JIRA 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>
	<?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.
	-->

	<!-- $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 Apache Maven as our
	build tool. We now use Maven 2 as our primary build platform (what
	we use to cut releases, for continuous integration builds, and for
	development). The sources can also be built using Ant (a working
	Ant build.xml is included in the top level project directory).
	To build commons math using Maven 2, you can follow the instructions for
	<a href="http://maven.apache.org/run-maven/index.html">Building a
	project with Maven 2</a>. Launch Maven from the top-level directory
	in the checkout of commons-math trunk. No special setup is required,
	except that currently to build the site (i.e. to execute Maven's
	"site" goal), you may need to increase the default memory allocation
	(e.g. <code>export MAVEN_OPTS=-Xmx512m</code>) before launching
	Maven.
	</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="https://issues.apache.org/jira/secure/Signup!default.jspa">
	Setup an account on JIRA</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>
	See the <a href="http://commons.apache.org/math/issue-tracking.html">
	Commons Math Issue Tracking Page</a> for more information on how to
	search for or submit bugs or enhancement requests.
	</p>
	<li>
	Generating patches: The requested format for generating patches is
	the Unified Diff format, which can be easily generated using the svn
	client or various IDEs.
	<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]
	Principal 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 JIRA ticket using the the feature title as the short
	description. Incorporate feedback from the initial posting in the
	description. Add a reference to the JIRA ticket to the WishList entry.
	</li>
	<li>Submit code as attachments to the JIRA 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>