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.
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.
- Start by reviewing the overall objectives stated in the main page upon which the project is founded.
- Download the Hipparchus source code. The git url for the current development sources of Hipparchus https://github.com/Hipparchus-Math/hipparchus
- Hipparchus uses Apache Maven as our build tool. The sources can also be built using any IDE. To build Hipparchus, you can follow the instructions from the building page
- Be sure to join the users and developers email lists and use them appropriately. Make any proposals here where the group can comment on them.
- Setup an account on GitHub and use it to submit pull requests and identify bugs. Read the GitHub help.
- Generating patches: The requested format for generating patches is either GitHub pull requests or patches using the Unified Diff format, which can be easily generated using the git client or various IDEs.
Contributing ideas and code
Follow the steps below when making suggestions for additions or enhancements to Hipparchus. 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 developers mailing list, with a good, short title describing the new feature or enhancement. For example, “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 developers list, the next step is to create a ticket for a new issue in the Hipparchus issues tracker
- Submit code as pull requests or as patchs. Please use one ticket for each feature, adding multiple pull requests 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 too patient) with committers reviewing patches. Post a nudge message to developers list with a reference to the issue if a patch goes more than a few days with no comment or commit.
Hipparchus follows a specific coding style, similar to the ones used in Apache Commons projects or the Orekit project. The reference settings correspond to the src/conf/checkstyle.xml file found in the Hipparchus source tree. There is also a src/conf/hipparchus-eclipse.xml file that configures the eclipse formater in a mostly compatible way (there are some parts that cannot be configured automatically in Eclipse to match checkstyle settings, mainly in the indentation parts). 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 configure the user.name, user.email and core.autocrlf git repository or global settings with git config. 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 true (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 input (thus forcing git to only strip accidental CR/LF when committing into the repository, but never when cheking out files from the repository). See Customizing Git - Git Configuration in the git book for explanation about how to configure these settings and more.
- 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.
- Exceptions generated by Hipparchus are all unchecked.
- All public methods advertise all exceptions that they can generate. Exceptions must be documented in both javadoc and method signatures and the documentation in the javadoc must include full description of the conditions under which exceptions are thrown.
- Methods should fully specify parameter preconditions required for successful activation. When preconditions are violated, a MathIllegalArgumentException should be thrown. Exception messages must contain sufficient information on parameter values to determine the exact precondition failure.
- 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 Hipparchus project header in a comment that begins the file,
- Recurring contributors must file an Hipparchus Individual Contributor License Agreement (ICLA) (Open Document Format, Portable Document Format) or Corporate Contributor License Agreement (CCLA) (Open Document Format, Portable Document Format)
- Importing pre-existing code into Hipparchus requires filing a Software Grant (Portable Document Format)
- 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 developers mailing list before contributing or committing code.
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.