Skip to content
Permalink
Browse files
Update developer guide
Drop reference to building with ant.

Add notes about contributing using GitHub PRs.
  • Loading branch information
aherbert committed Apr 12, 2022
1 parent 30b91a1 commit ecaac6d6f475854e5bafa9a712180a8e0e27bc8e
Showing 1 changed file with 65 additions and 47 deletions.
@@ -46,24 +46,23 @@
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 class="none">http://gitbox.apache.org/repos/asf/commons-rng.git</source>
is <source>http://gitbox.apache.org/repos/asf/commons-rng.git</source>
for anonymous read-only access and
<source class="none">https://apacheid@gitbox.apache.org/repos/asf/commons-rng.git</source>
<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. The sources can also be built using Ant (a working
Ant build.xml is included in the top level project directory).
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
"<kbd>site</kbd>" goal), you may need to increase the default memory allocation
(e.g. <kbd>export MAVEN_OPTS=-Xmx512m</kbd>) before launching
"site" goal), you may need to increase the default memory allocation
(e.g. <code>export MAVEN_OPTS=-Xmx512m</code>) before launching
Maven.
</li>
<li>
@@ -83,20 +82,25 @@
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="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.
</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 class="none">git diff -p > patch </source>
Run this command from the top-level project directory (where pom.xml
resides).
</li>
<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>
@@ -122,40 +126,54 @@
useful</li>
</ul></li>
<li>Assuming a generally favorable response to the idea on commons-dev,
create a JIRA ticket using the the feature title as the short
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.
description. Add a reference to the discussion thread.
</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>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/technetwork/java/codeconventions-150003.pdf">Code
Conventions for the Java Programming Language</a>. As part of the maven
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 <kbd>checkstyle.xml</kbd>.
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 code code.
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 git repository or global settings for:
</p>
<source>user.name
user.email</source>
<p>These settings define the identity and mail of the committer. See <a
href="https://www.git-scm.com/book/en/Customizing-Git-Git-Configuration">Customizing
Git - Git Configuration</a> in the git book for explanation about how to
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>
@@ -177,13 +195,13 @@ user.email</source>
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 <kbd>\(</kbd> and <kbd>\)</kbd>
for inline formulas (or <kbd>\[</kbd> and <kbd>\]</kbd> to have the formula
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,
<kbd>\(</kbd> <kbd>a^2 + b^2 = c^2</kbd> <kbd>\)</kbd>
<code>\(</code><code>a^2 + b^2 = c^2</code><code>\)</code>
will render an in-line formula
saying that <kbd>(a, b, c)</kbd> is a Pythagorean triplet: \( a^2 + b^2 = c^2 \).
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.
@@ -236,8 +254,8 @@ user.email</source>
</li>
<li>
All contributions must comply with the terms of the Apache
<a href="https://www.apache.org/licenses/contributor-agreements.html">Contributor License
Agreement (CLA)</a>.
<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"

0 comments on commit ecaac6d

Please sign in to comment.