You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by bu...@apache.org on 2014/12/23 18:39:18 UTC
svn commit: r933796 - in /websites/staging/sis/trunk/content: ./ build.html
code-patterns.html contributor.html source.html
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-->