Contributing

Getting Started

1. Download the Commons RNG source code. Follow the instructions under the heading "Repository Checkout" on the Git at the ASF page. The git url for the current development sources of Commons RNG is

   http://gitbox.apache.org/repos/asf/commons-rng.git

   for anonymous read-only access and

   https://apacheid@gitbox.apache.org/repos/asf/commons-rng.git

   (where apacheid should be replaced by each committer Apache ID) for committers read-write access.
2. Like most commons components, Commons RNG uses Apache Maven as our build tool. To build Commons RNG using Maven, you can follow the instructions for Building a project with Maven. Launch Maven from the top-level directory in the checkout of Commons RNG 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.
3. Be sure to join the commons-dev and commons-user email lists and use them appropriately (make sure the string "[RNG]" starts the Subject line of all your postings). Make any proposals here where the group can comment on them.
4. 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 RNG Issue Tracking Page for more information on how to search for or submit bugs or enhancement requests.
5. 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.

   git diff -p > patch 

   Run this command from the top-level project directory (where pom.xml resides).
6. Pull Requests: We accept pull requests (PRs) via the GitHub repository mirror. The Commons RNG repository can be forked and changes merged via a PR. See collaborating with pull requests for more information on pull requests.

Contributing ideas and code

Follow the steps below when making suggestions for additions or enhancements to Commons RNG. 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!

1. Start with a post to the commons-dev mailing list, with [RNG] at the beginning of the subject line, followed by a short title describing the new feature or enhancement; for example, "[RNG] New cryptographically secure generator". 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
2. Assuming a generally favorable response to the idea on commons-dev, the next step is to file a report on the issue-tracking system (JIRA). 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 discussion thread.
3. 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.
   • A pull request (PR) via GitHub. To link the PR to a corresponding JIRA ticket prefix the PR title with STATISTICS-xxx: where xxx is the issue number.
     Please include quality commit messages with a single line title of about 50 characters, followed by a blank line, followed by a more detailed explanation of the changeset. The title should be prefixed with the JIRA ticket number if applicable, e.g. STATISTICS-xxx: New univariate distribution. See contributing to a project in the git book for guidelines on commit messages.
   Be patient (but not too patient) with committers reviewing patches/PRs. Post a *nudge* message to commons-dev with a reference to the ticket if a submission goes more than a few days with no comment or commit.

Coding Style

Commons RNG follows Code Conventions for the Java Programming Language (circa 1999). As part of the maven build process, style checking is performed using the Checkstyle plugin, using the properties specified in checkstyle.xml. This is based on the default sun checks defined by the Checkstyle plugin using current Java best practices. 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 configure the user.name and user.email git repository or global settings with git config. These settings define the identity and mail of the committer. See Customizing Git - Git Configuration in the git book for an explanation about how to configure these settings and more.

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 the terms used in component documentation must be provided.
• Commons RNG javadoc generation supports embedded LaTeX formulas via the MathJax 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 a Pythagorean triplet: \( a^2 + b^2 = c^2 \).
  See the MathJax and LaTex documentation for details on how to represent formulas and escape special characters.
• 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

• Exceptions generated by Commons RNG are all unchecked.
• All public methods advertise all exceptions that they can generate. Exceptions must be documented in Javadoc and the documentation must include full description of the conditions under which exceptions are thrown.

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.

It must be noted that, due to the nature of random number generation, some unit tests are bound to fail with some probability. This is applicable for tests that compare random output to an expected distribution. These tests should not use a fixed seed to ensure consistent output. The 'maven-surefire-plugin' is configured to re-run tests that fail, and pass the build if they succeed within the allotted number of reruns (the test will be marked as 'flaky' in the report). Any test that is consistently 'flaky' may require an update to the test assumptions and assertions.

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.