Developers Guide

Developers are asked to comply with the following development guidelines. Code that does not comply with the guidelines including the word must will not be committed. Our aim will be to fix all of the exceptions to the "should" guidelines prior to a release.

Getting Started

Start by reviewing the overall objectives stated in the proposal upon which the project is founded.
Download the commons math source code. Follow the instructions under the heading "Anonymous Subversion" on the Apache version control page (Also have a look at the Jakarta wiki svn page ) to check out the commons math code base from Subversion. The svn url for the current development sources of commons-math is https://svn.apache.org/repos/asf/jakarta/commons/proper/math/trunk
Like most commons components, commons-math uses maven as our build tool. Follow the building components instructions to get set up with maven so that you can build commons-math from source.
Have a look at the new features that users and developers have requested on the Math Wish List Wiki Page.
Be sure to join the commons-dev and commons-user email lists 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.
Setup an account on Bugzilla and use it to submit patches and identify bugs. Read the directions for submitting bugs and search the database to determine if an issue exists or has already been dealt with.
Submitting Issues:
- Bookmarkable Template for submitting patches.
- Bookmarkable Template for submitting bugs.
Querying the Database:
- New and Existing Issues.
- Resolved and Closed Issues.
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. svn diff > patch

Contributing ideas and code

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!

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 as brief as possible):
- A concise description of the new feature / enhancement
- 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
- Some indication of why the addition / enhancement is practically useful
Assuming a generally favorable response to the idea on commons-dev, the next step is to add an entry to the Math Wish List 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.
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.
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 too 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.

Commons-math follows Code Conventions for the Java Programming Language. As part of the maven build process, style checking is performed using the Checkstyle plugin, using the properties specified in checkstyle.xml. Committed code should 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.

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 Apache Source Code Repositories page.

Committed code must include full javadoc.
All component contracts must be fully specified in the javadoc class, interface or method comments, including specification of acceptable ranges of values, exceptions or special return values.
External references or full statements of definitions for all mathematical terms used in component documentation must be provided.
Implementations should use standard algorithms and references or full descriptions of all algorithms should be provided.
Additions and enhancements should include updates to the User Guide.

Committed code must include unit tests.
Unit tests should provide full path coverage.
Unit tests should 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.

All new source file submissions must include the Apache Software License in a comment that begins the file
All contributions must comply with the terms of the Apache Contributor License Agreement (CLA)
Patches must 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.).
References to source materials covered by restrictive proprietary licenses should be avoided. In particular, contributions should not implement or include references to algorithms in Numerical Recipes (NR). Any questions about copyright or patent issues should be raised on the commons-dev mailing list before contributing or committing code.