| <?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 \( and \) for inline |
| formulas, or \[ and \] to have the formula appear on a separate line. |
| For example, \(a^2 + b^2 = c^2\) will render an in-line formula |
| saying that (a, b, c) is Pythagorean triplet. Using \[ and \] 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> |
