You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ah...@apache.org on 2022/03/06 22:54:23 UTC
[commons-statistics] 02/03: Update developer guide
This is an automated email from the ASF dual-hosted git repository.
aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-statistics.git
commit e56c177acb8663cea11dc7af44a13d9736298a29
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Sun Mar 6 22:33:29 2022 +0000
Update developer guide
Remove reference to building using ant.
Remove reference to non-existent wiki.
Add sections about GitHub PRs.
Remove git config for setting core.autocrlf. The project uses a
.gitattributes file to define this setting for the text files in the
repository.
Use https links. Fix broken/outdated links.
---
src/site/xdoc/developers.xml | 114 ++++++++++++++++++++++---------------------
1 file changed, 59 insertions(+), 55 deletions(-)
diff --git a/src/site/xdoc/developers.xml b/src/site/xdoc/developers.xml
index b495a88..5969191 100644
--- a/src/site/xdoc/developers.xml
+++ b/src/site/xdoc/developers.xml
@@ -55,8 +55,7 @@
</li>
<li>
Like most commons components, Commons Statistics 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 Statistics using Maven, you can follow the instructions for
<a href="http://maven.apache.org/run-maven/index.html">Building a
project with Maven</a>.
@@ -68,11 +67,6 @@
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/StatisticsWishList">
- Statistics 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
@@ -89,20 +83,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/statistics/issue-tracking.html">
- Commons Statistics 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>
+ <br/>
+ See the <a href="https://commons.apache.org/statistics/issue-tracking.html">
+ Commons Statistics 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 Statistics 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>
@@ -116,7 +115,7 @@
<li>Start with a post to the commons-dev mailing list, with [Statistics] at
the beginning of the subject line, followed by a short title
describing the new feature or enhancement; for example, "[Statistics]
- New cryptographically secure generator".
+ New univariate distribution".
The body of the post should include each of the following items
(but be <strong>as brief as possible</strong>):
<ul>
@@ -128,21 +127,32 @@
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/StatisticsWishList">Statistics 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
+ 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 JIRA ticket to the WishList entry.
+ 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>
</p>
@@ -150,28 +160,22 @@
<subsection name='Coding Style'>
<p>
- Commons Statistics follows <a href="http://java.sun.com/docs/codeconv/">Code
- Conventions for the Java Programming Language</a>. As part of the maven
+ Commons Statistics 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>.
+ 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 <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
+ 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>
@@ -191,7 +195,7 @@
</li>
<li>
Commons Statistics javadoc generation supports embedded LaTeX formulas via the
- <a href="http://www.mathjax.org">MathJax</a> javascript display engine.
+ <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
@@ -252,8 +256,8 @@
</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>.
+ <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"
@@ -266,7 +270,7 @@
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>.
+ <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>