sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r933796 - in /websites/staging/sis/trunk/content: ./ build.html code-patterns.html contributor.html source.html
Date Tue, 23 Dec 2014 17:39:18 GMT
Author: buildbot
Date: Tue Dec 23 17:39:17 2014
New Revision: 933796

Log:
Staging update by buildbot for sis

Modified:
    websites/staging/sis/trunk/content/   (props changed)
    websites/staging/sis/trunk/content/build.html
    websites/staging/sis/trunk/content/code-patterns.html
    websites/staging/sis/trunk/content/contributor.html
    websites/staging/sis/trunk/content/source.html

Propchange: websites/staging/sis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Dec 23 17:39:17 2014
@@ -1 +1 @@
-1647565
+1647622

Modified: websites/staging/sis/trunk/content/build.html
==============================================================================
--- websites/staging/sis/trunk/content/build.html (original)
+++ websites/staging/sis/trunk/content/build.html Tue Dec 23 17:39:17 2014
@@ -110,7 +110,7 @@ from the SIS project root:</p>
 Pack200 files are uncompressed by the <code>unpack200</code> command provided
in JDK/JRE installation.
 However for users convenience, we provide a shell script for uncompressing and launching
the SIS
 command line tool in a single step. That shell script, together with the Pack200 file and
other
-files (<code>README</code>, <code>LICENSE</code>, <etc.>) are
bundled in a ZIP file created as below:</p>
+files (<code>README</code>, <code>LICENSE</code>, <i>etc.</i>)
are bundled in a ZIP file created as below:</p>
 <div class="codehilite"><pre>mvn org.apache.sis.core:sis-build-helper:dist --non-recursive
 </pre></div>
 

Modified: websites/staging/sis/trunk/content/code-patterns.html
==============================================================================
--- websites/staging/sis/trunk/content/code-patterns.html (original)
+++ websites/staging/sis/trunk/content/code-patterns.html Tue Dec 23 17:39:17 2014
@@ -99,6 +99,11 @@
 <li><a href="#unicode-loop">Loop over character sequences using code points</a></li>
 </ul>
 </li>
+<li><a href="#logging">Logging</a><ul>
+<li><a href="#logger-name">Logger name</a></li>
+<li><a href="#logging-level">Logging level</a></li>
+</ul>
+</li>
 </ul>
 </div>
 <h1 id="referencing">Referencing</h1>
@@ -150,6 +155,28 @@ Consequently, when iterating over charac
     <span class="n">i</span> <span class="o">+=</span> <span class="n">Character</span><span
class="o">.</span><span class="na">charCount</span><span class="o">(</span><span
class="n">c</span><span class="o">);</span>
 <span class="o">}</span>
 </pre></div>
+
+
+<h1 id="logging">Logging</h1>
+<p>Apache SIS uses the <code>java.util.logging</code> framework with one
minor difference:
+instead of invoking the <code>getLogger(String)</code> method provided by the
<code>java.util.logging.Logger</code> class,
+we rather invoke the method provided by the <code>apache.sis.util.logging.Logging</code>
class.
+The result is identical by default,
+but the SIS method gives us a chance to redirect the logging to an other framework like Log4J
if desired.
+The difference between the SIS approach and other facades like <code>common-logging</code>
is that
+SIS uses the standard Java API (except for the above-cited <code>getLogger</code>
method) instead than defining new API.</p>
+<h2 id="logger-name">Logger name</h2>
+<p>The name given in argument to the <code>getLogger(String)</code> method
is usually the package name of the class
+emitting the log messages, but not necessarily. In particular, we do not follow this convention
if the class
+is located in an internal package (<code>org.apache.sis.internal.*</code>) since
those packages are considered privates.
+In such case, the logger name should be the package name of the public class that use the
internal class.</p>
+<p>The reason for the above rule is that logger names are considered part of the public
API,
+since developers use them for configuring their logging (verbosity, destination, <i>etc.</i>).
+Note that the "real" package name of the emitter is available by <code>LogRecord.getSourceClassName()</code>.</p>
+<h2 id="logging-level">Logging level</h2>
+<p>All logging at <code>Level.INFO</code> or above shall be targeted to
users or administrators, not to developers.
+In particular <code>Level.SEVERE</code> shall be reserved for critical errors
that compromise the application stability —
+it shall not be used for exceptions thrown while parsing user data (file or database).</p>
             </article>
           </section>
         </div><!--/span-->

Modified: websites/staging/sis/trunk/content/contributor.html
==============================================================================
--- websites/staging/sis/trunk/content/contributor.html (original)
+++ websites/staging/sis/trunk/content/contributor.html Tue Dec 23 17:39:17 2014
@@ -100,7 +100,8 @@ effective computer programming.</p>
 <li><a href="#modules">The SIS library modules</a></li>
 </ul>
 </li>
-<li><a href="#source">Fetching and editing source code</a><ul>
+<li><a href="#source">Fetching and editing source code</a></li>
+<li><a href="#commit">Committing changes</a><ul>
 <li><a href="#svn-config">Configuring Subversion properties</a></li>
 </ul>
 </li>
@@ -176,10 +177,24 @@ mvn install
 </pre></div>
 
 
+<p>The <a href="source.html">source code</a> page provides tips for opening
the files in an IDE,
+and guidelines about the way SIS source code is organized.</p>
+<h1 id="commit">Committing changes</h1>
+<p>Copies or displacements of files shall be done with the <code>svn copy</code>
or <code>svn move</code> command, respectively.
+Be aware that not all IDE or graphical tools perform this action appropriately.
+<em>Always verify on the command-line</em>, at least the first times that a new
tools is used, by executing <code>svn status</code>.
+Files that have been moved or copied shall have a <code>A+</code> symbol in the
left margin, like below:</p>
+<div class="codehilite"><pre>D       my-directory/the-old-filename
+A  +    my-directory/the-new-filename
+</pre></div>
+
+
+<p>Using the proper SVN command is necessary for preserving the history, preserving
the <a href="#svn-config">SVN properties</a>,
+and consuming less space on the Apache server hosting the source code repository.</p>
 <h2 id="svn-config">Configuring Subversion properties</h2>
 <p>Subversion can associate properties to each tracked files. Those properties tell
to Subversion
 how to handle platform-specific aspects like end-of-line characters, and how to serve the
files
-to web browsers (MIME type, encoding, <etc.>).
+to web browsers (MIME type, encoding, <i>etc.</i>).
 Those properties are typically set when a new file is added, not during modifications.
 Developers can specify default properties for all their Subversion working copies as below:</p>
 <ul>
@@ -188,8 +203,13 @@ Developers can specify default propertie
 <li>Scroll down to the <code>[auto-props]</code> section and make sure
to assign the appropriate
     (usually <code>native</code>) value to the End Of Line (EOL) style of the
files to be edited.</li>
 </ul>
-<p>Below is an example of a portion of Subversion configuration file:</p>
+<p>Below is an example of a portion of Subversion configuration file
+(real configuration files are typically larger):</p>
 <div class="codehilite"><pre><span class="k">[miscellany]</span>
+<span class="c"># Whitespace-delimited globs which Subversion will ignore in its &#39;status&#39;
output.</span>
+<span class="na">global-ignores</span> <span class="o">=</span> <span
class="s">*.class *.jar .* *~</span>
+
+<span class="c"># Enables automatic properties (defined below) for &#39;svn add&#39;
and &#39;svn import&#39;.</span>
 <span class="na">enable-auto-props</span> <span class="o">=</span>
<span class="s">yes</span>
 
 <span class="c"># Section for configuring automatic properties.</span>

Modified: websites/staging/sis/trunk/content/source.html
==============================================================================
--- websites/staging/sis/trunk/content/source.html (original)
+++ websites/staging/sis/trunk/content/source.html Tue Dec 23 17:39:17 2014
@@ -103,14 +103,19 @@ For fetching the source code, choose one
 <li><a href="#eclipse">Eclipse</a></li>
 </ul>
 </li>
-<li><a href="#classes-naming">Classes naming convention</a></li>
+<li><a href="#license">License header</a></li>
+<li><a href="#naming">Naming convention</a></li>
 <li><a href="#formatting">Code formatting</a><ul>
+<li><a href="#spaces">Spaces and line length</a></li>
+<li><a href="#declarations">Declarations</a></li>
+</ul>
+</li>
+<li><a href="#javadoc">Documentation formatting</a><ul>
 <li><a href="#javadoc-tags">Javadoc annotations</a></li>
 <li><a href="#html">HTML elements</a></li>
 <li><a href="#mathml">MathML elements</a></li>
 <li><a href="#paragraph">Paragraphs</a></li>
 <li><a href="#css">Javadoc CSS</a></li>
-<li><a href="#miscellaneous">Miscellaneous</a></li>
 </ul>
 </li>
 </ul>
@@ -157,7 +162,17 @@ then execute the following steps:</p>
 <li>Go to <em>File</em> → <em>Import</em> → <em>General</em>
→ <em>Existing Projects in Workspace</em>.</li>
 <li>Choose the <code>sis</code> directory and import.</li>
 </ul>
-<h1 id="classes-naming">Classes naming convention</h1>
+<h1 id="license">License header</h1>
+<p>All Java source files (<code>*.java</code>) shall begin with the current
ASF license header as described in <a href="http://www.apache.org/legal/src-headers.html">ASF
Source Header</a>.
+Properties source files (<code>*.properties</code>) used as inputs to some processor
(e.g. the resource compiler)
+shall have the same license header, but with lines prefixed by <code>#</code>
instead of <code>*</code>.
+Properties files distributed as-is in the JAR files can summarize the license on a single
line for saving space,
+as below:</p>
+<div class="codehilite"><pre># Licensed to the Apache Software Foundation (ASF)
under one or more contributor license agreements.
+</pre></div>
+
+
+<h1 id="naming">Naming convention</h1>
 <p>Implementations of GeoAPI interfaces usually (but not always) begin with <code>Abstract</code>,
<code>Default</code>, <code>Simple</code> or <code>General</code>
prefixes.</p>
 <ul>
 <li>The <code>Abstract</code> prefix is used when a class is abstract according
<abbr title="International Organization for Standardization">ISO</abbr> specifications
— it may or may not be be abstract in the Java sense.</li>
@@ -182,6 +197,34 @@ Formatting the code in a way that emphas
 aligning identical terms in columns, can help to understand the overall pattern
 and to identify bugs. The decision to use standard or tabular format is made on
 a case-by-case basis. Of course, tabular format shall not be abused.</p>
+<h2 id="spaces">Spaces and line length</h2>
+<ul>
+<li><strong>Trailing Whitespaces:</strong> Remove all trailing whitespaces.<ul>
+<li>Eclipse users can use the <em>Source</em> - <em>Cleanup</em>
option to accomplish this.</li>
+<li>NetBeans users can use the use the <em>Source</em> - <em>Remove
trailing spaces</em> on a file-by-file basis,
+  or set the <em>Preferences</em> - <em>Editor</em> - <em>On
Save</em> - <em>Remove trailing whitespaces</em> option.</li>
+</ul>
+</li>
+<li><strong>Indentation:</strong> Use 4 space indents (except for XML files)
and never use tabs.<ul>
+<li>Use 2 space indents for XML files, because <abbr title="International Organization
for Standardization">ISO</abbr>/<abbr title="Open Geospatial Consortium">OGC</abbr>
XML schemas tend to have a very deep structure.</li>
+</ul>
+</li>
+<li><strong>Line wrapping:</strong> Use 120-column line width for Java
code and Javadoc.
+    Some exceptions to this rule may exist for preserving tabular structures, but should
be rare.</li>
+</ul>
+<h2 id="declarations">Declarations</h2>
+<p>Class, method and field declarations should use the keywords in the following order:</p>
+<ul>
+<li><code>public</code>, <code>protected</code> or <code>private</code></li>
+<li><code>abstract</code> or <code>static</code></li>
+<li><code>final</code></li>
+<li><code>strictfp</code> (should be applied on all test classes)</li>
+</ul>
+<p>This is known as the "customary order" in the <a href="http://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.1.1">Java
Language Specification</a>.</p>
+<h1 id="javadoc">Documentation formatting</h1>
+<p>Apache SIS uses the standard Javadoc conventions, except for the 80 characters line
length restriction.
+Javadoc lines should not exceed 120 characters, but exceptions to this rule may exist for
preserving the
+structure of <code>&lt;table&gt;</code> elements.</p>
 <h2 id="javadoc-tags">Javadoc annotations</h2>
 <p>SIS uses standard javadoc annotations. The meaning of some tags are refined as below:</p>
 <ul>
@@ -298,22 +341,6 @@ Instead, rely on styling. Some HTML tags
 </tr>
 </tbody>
 </table>
-<h2 id="miscellaneous">Miscellaneous</h2>
-<ul>
-<li><strong>License Header:</strong> Always add the current ASF license
header as described in <a href="http://www.apache.org/legal/src-headers.html">ASF Source
Header</a>.</li>
-<li><strong>Trailing Whitespaces:</strong> Remove all trailing whitespaces.<ul>
-<li>Eclipse users can use the <em>Source</em> - <em>Cleanup</em>
option to accomplish this.</li>
-<li>NetBeans users can use the use the <em>Source</em> - <em>Remove
trailing spaces</em> on a file-by-file basis,
-  or set the <em>Preferences</em> - <em>Editor</em> - <em>On
Save</em> - <em>Remove trailing whitespaces</em> option.</li>
-</ul>
-</li>
-<li><strong>Indentation:</strong> Use 4 space indents (except for XML files)
and never use tabs!<ul>
-<li>Use 2 space indents for XML files, because <abbr title="International Organization
for Standardization">ISO</abbr>/<abbr title="Open Geospatial Consortium">OGC</abbr>
XML schemas tend to have a very deep structure.</li>
-</ul>
-</li>
-<li><strong>Line wrapping:</strong> Use 120-column line width for Java
code and Javadoc.
-    Some exceptions to this rule may exist for preserving tabular structures, but should
be rare.</li>
-</ul>
             </article>
           </section>
         </div><!--/span-->



Mime
View raw message