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-->


Reply via email to