| <?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> |
| <p> |
| <ol> |
| <li> |
| Download the Commons RNG source code. Follow the instructions |
| under the heading "Repository Checkout" on the |
| <a href="https://git-wip-us.apache.org/">Git at the ASF page</a>. |
| The git url for the current development sources of Commons RNG |
| is <source>http://git-wip-us.apache.org/repos/asf/commons-rng.git</source> |
| for anonymous read-only access and |
| <source>https://apacheid@git-wip-us.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. The sources can also be built using Ant (a working |
| Ant build.xml is included in the top level project directory). |
| To build Commons RNG using Maven, you can follow the instructions for |
| <a href="http://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> |
| Have a look at the new features that users and developers have requested |
| on the <a href="http://wiki.apache.org/commons/RngWishList"> |
| RNG Wish List Wiki Page.</a> |
| </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="http://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. |
| <p> |
| See the <a href="http://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. |
| </p> |
| <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> |
| </ol> |
| </p> |
| <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! |
| <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 add an entry to the |
| <a href="http://wiki.apache.org/commons/RngWishList">RNG Wish |
| List</a> corresponding to the idea. Include a reference to the |
| discussion thread. </li> |
| <li>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. |
| </li> |
| <li>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. Be |
| patient (but not <strong>too</strong> 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. |
| </li> |
| </ol> |
| </p> |
| </subsection> |
| |
| <subsection name='Coding Style'> |
| <p> |
| Commons RNG follows <a href="http://java.sun.com/docs/codeconv/">Code |
| Conventions for the Java Programming Language</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>. |
| 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 <source>user.name</source>, |
| <source>user.email</source> and <source>core.autocrlf</source> |
| git repository or global settings with <source>git config</source>. |
| 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 |
| <source>true</source> (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 <source>input</source> |
| (thus forcing git to only strip accidental CR/LF when committing into |
| the repository, but never when cheking out files from the repository). See <a |
| href="http://www.git-scm.com/book/en/Customizing-Git-Git-Configuration">Customizing |
| Git - Git Configuration</a> in the git book for 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="http://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="http://www.apache.org/licenses/cla.pdf">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://www.nr.com/">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> |
