| <?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> |
| Maintenance of a library by decentralized team requires communication. |
| 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> |
| <ol> |
| <li> |
| Download the Commons RNG source code. Follow the instructions |
| under the heading "Repository Checkout" on the |
| <a href="https://gitbox.apache.org/">Git at the ASF page</a>. |
| The git url for the current development sources of Commons RNG |
| is <source>http://gitbox.apache.org/repos/asf/commons-rng.git</source> |
| for anonymous read-only access and |
| <source>https://apacheid@gitbox.apache.org/repos/asf/commons-rng.git</source> |
| (where apacheid should be replaced by each committer Apache ID) for committers |
| read-write access. |
| </li> |
| <li> |
| 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 |
| <a href="https://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 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. <code>export MAVEN_OPTS=-Xmx512m</code>) before launching |
| Maven. |
| </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 |
| "[RNG]" 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="https://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. |
| <br/> |
| See the <a href="https://commons.apache.org/rng/issue-tracking.html"> |
| Commons RNG Issue Tracking Page</a> |
| for more information on how to |
| search for or submit bugs or enhancement requests. |
| </li> |
| <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> |
| 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 <a href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests"> |
| collaborating with pull requests</a> for more information on pull requests. |
| </li> |
| </ol> |
| <p><strong>Contributing ideas and code</strong></p> |
| <p> |
| 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! |
| </p> |
| <ol> |
| <li>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 <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 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. |
| </li> |
| <li>Submit code as: |
| <ul> |
| <li>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. |
| </li> |
| <li>A pull request (PR) via GitHub. |
| To link the PR to a corresponding JIRA ticket prefix the PR title with |
| <code>STATISTICS-xxx:</code> where <code>xxx</code> is the issue number.<br/> |
| 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. <code>STATISTICS-xxx: New univariate distribution</code>. |
| See <a href="https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project"> |
| contributing to a project</a> in the git book for guidelines on commit messages. |
| </li> |
| </ul> |
| Be patient (but not <strong>too</strong> 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. |
| </li> |
| </ol> |
| </subsection> |
| |
| <subsection name='Coding Style'> |
| <p> |
| Commons RNG follows <a href="https://www.oracle.com/java/technologies/javase/codeconventions-contents.html"> |
| Code Conventions for the Java Programming Language (circa 1999)</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>. This is based on |
| the default <a href="https://github.com/checkstyle/checkstyle/blob/master/src/main/resources/sun_checks.xml"> |
| sun checks</a> defined by the Checkstyle plugin using current Java best practices. |
| 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 <code>user.name</code> and <code>user.email</code> |
| git repository or global settings with <code>git config</code>. |
| These settings define the identity and mail of the committer. See <a |
| href="https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration">Customizing |
| Git - Git Configuration</a> in the git book for an 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 the |
| terms used in component documentation <i>must</i> be provided. |
| </li> |
| <li> |
| Commons RNG javadoc generation supports embedded LaTeX formulas via the |
| <a href="https://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 <code>\(</code> and <code>\)</code> |
| for inline formulas (or <code>\[</code> and <code>\]</code> to have the formula |
| appear on a separate line). |
| For example, |
| <code>\(</code><code>a^2 + b^2 = c^2</code><code>\)</code> |
| will render an in-line formula |
| saying that (a, b, c) is a Pythagorean triplet: \( a^2 + b^2 = c^2 \). |
| <br/> |
| 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 RNG are all unchecked. |
| </li> |
| <li> |
| All public methods advertise all exceptions that they can generate. |
| Exceptions <i>must</i> be documented in Javadoc and the documentation |
| <i>must</i> include full description of the conditions under which |
| exceptions are thrown. |
| </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="https://www.apache.org/licenses/contributor-agreements.html#clas"> |
| 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://numerical.recipes/">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> |
| </body> |
| </document> |