src/site/xdoc/developers.xml - commons-rng - Git at Google

 <?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>
         <p>
           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 <i>should</i> <b>not</b>
           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.
         </p>
       </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>
	<?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>
	<p>
	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 <i>should</i> <b>not</b>
	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.
	</p>
	</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>