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 'status' 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 'svn add' and 'svn import'.</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><table></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-->