<?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.
  -->
  
<document>
 <properties>
  <title>Developers Guide</title>
 </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 "Repository Checkout" on the
        <a href="https://git-wip-us.apache.org/">Git at the ASF page</a>.
        The git url for the current development sources of Commons Math
        is <source>http://git-wip-us.apache.org/repos/asf/commons-math.git</source>
        for anonymous read-only access and
        <source>https://apacheid@git-wip-us.apache.org/repos/asf/commons-math.git</source>
        (where apacheid should be replaced by each committer Apache ID) for committers
        read-write access.
        </li>
        <li>Like most commons components, Commons Math uses Apache Maven as our
            build tool. 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, you can follow the instructions for
            <a href="http://maven.apache.org/run-maven/index.html">Building a
            project with Maven</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 git
          client or various IDEs.
<source>git diff -p > patch </source>
          Run this command from the top-level project directory (where pom.xml
          resides).
        </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. </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 git 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 configure the <source>user.name</source>,
     <source>user.email</source> and <source>core.autocrlf</source>
     git repository or global settings with <source>git config</source>.
     The first two settings define the identity and mail of the committer.
     The third setting deals with line endings to achieve consistency
     in line endings. Windows users should configure this setting to
     <source>true</source> (thus forcing git to convert CR/LF line endings
     in the workspace while maintaining LF only line endings in the repository)
     while OS X and Linux users should configure it to <source>input</source>
     (thus forcing git to only strip accidental CR/LF when committing into
     the repository, but never when cheking out files from the repository). See <a
     href="http://www.git-scm.com/book/en/Customizing-Git-Git-Configuration">Customizing
     Git - Git Configuration</a> in the git book for explanation about how to
     configure these settings and more.
    </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>
      Commons math javadoc generation now supports embedded LaTeX formulas via the
      <a href="http://www.mathjax.org">MathJax</a> javascript display engine. To
      embed mathematical expressions formatted in LaTeX in javadoc, simply surround
      the expression to be formatted with either &#92;( and &#92;) for inline
      formulas, or &#92;[ and &#92;] to have the formula appear on a separate line.
      For example, &#92;(a^2 + b^2 = c^2&#92;) will render an in-line formula
      saying that (a, b, c) is Pythagorean triplet.  Using &#92;[ and &#92;] on
      the ends will render the same formula on a separate line.  See the MathJax
      and LaTex documentation for details on how to represent formulas and
      escape special characters.</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='Exceptions'>
    <ul>
      <li>
      Exceptions generated by Commons Math are all unchecked.</li>
      <li>
      All public methods advertise all exceptions that they can generate.
      Exceptions <i>must</i> be documented in both javadoc and method signatures
      and the documentation in the javadoc <i>must</i> include full description
      of the conditions under which exceptions are thrown.</li>
      <li>
      Methods <i>should</i> fully specify parameter preconditions required for
      successful activation.  When preconditions are violated, a
      MathIllegalArgumentException should be thrown.  Subclasses of
      MathIllegalArgumentException may be used to represent common parameter
      contract violations (for example, NoBracketingException).  Exception
      messages <i>must</i> contain sufficient information on parameter values to
      determine the exact precondition failure.</li>
      <li>
      Exceptions generated by Commons Math make sense without knowing
      implementation details other than those stated in the public API.
      For example, a NoBracketingException makes sense thrown by a solver that
      has a precondition requiring that initial points bracket a root. This
      exception does not make sense, however, thrown by an inverse cumulative
      probability estimator.</li>
      <li>
      MathIllegalArgumentException should only be thrown in situations
      where preconditions can be exhaustively provided so that what arguments
      are "illegal" can be specified fully to the caller. Domain-specific
      exceptions need to be defined for cases where failures cannot be
      attributed to parameter precondition violation. For example, the exact
      domain of successful activation of a solver or quadrature method may be
      impossible to specify because of numerical properties of the method.
      If a solver fails to find a root or a quadrature method fails to converge
      for a given set of parameters, <i>unless those parameters violate the
      advertised preconditions</i> it is not appropriate to throw 
      MathIllegalArgumentException.</li>
      <li>
      State information included in exception messages <i>must</i> be available
      in exception properties - i.e., successful handling or reporting of 
      Commons Math exceptions must not require parsing exception messages.</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.pdf">
       http://www.validlab.com/goldberg/paper.pdf
      </a><br/>
      <a href="http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF">
       http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF
      </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>