Aims
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.
Guidelines
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.
Contributing
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
Commons 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/commons/proper/math/trunk
- 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 Maven 1.0.2 or
Ant (a working Maven 1 project.xml and Ant build.xml are included
in the top level project directory). To build commons math using
Maven 2, you can follow the instructions for
Building a
project with Maven 2
. 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.
export MAVEN_OPTS=-Xmx512m
) before launching
Maven.
- 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 JIRA
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.
See the
Commons Math Issue Tracking Page
for more information on how to
search for or submit bugs or enhancement requests.
-
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.
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]
Principal 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 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.
- 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 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.
Coding Style
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.
Documentation
-
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.
Unit Tests
-
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.
Licensing and copyright
-
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.
Recommended Readings
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.