sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1647622 - in /sis/site/trunk/content: build.mdtext code-patterns.mdtext contributor.mdtext source.mdtext
Date Tue, 23 Dec 2014 17:39:11 GMT
Author: desruisseaux
Date: Tue Dec 23 17:39:11 2014
New Revision: 1647622

URL: http://svn.apache.org/r1647622
Log:
Added more developer guidance.

Modified:
    sis/site/trunk/content/build.mdtext
    sis/site/trunk/content/code-patterns.mdtext
    sis/site/trunk/content/contributor.mdtext
    sis/site/trunk/content/source.mdtext

Modified: sis/site/trunk/content/build.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/build.mdtext?rev=1647622&r1=1647621&r2=1647622&view=diff
==============================================================================
--- sis/site/trunk/content/build.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/build.mdtext [UTF-8] Tue Dec 23 17:39:11 2014
@@ -38,7 +38,7 @@ The Pack200 bundle is a file with the `.
 Pack200 files are uncompressed by the `unpack200` 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 (`README`, `LICENSE`, <etc.>) are bundled in a ZIP file created as below:
+files (`README`, `LICENSE`, <i>etc.</i>) are bundled in a ZIP file created as
below:
 
     :::bash
     mvn org.apache.sis.core:sis-build-helper:dist --non-recursive

Modified: sis/site/trunk/content/code-patterns.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/code-patterns.mdtext?rev=1647622&r1=1647621&r2=1647622&view=diff
==============================================================================
--- sis/site/trunk/content/code-patterns.mdtext (original)
+++ sis/site/trunk/content/code-patterns.mdtext Tue Dec 23 17:39:11 2014
@@ -113,6 +113,44 @@ Consequently, when iterating over charac
 
 
 
+
+Logging    {#logging}
+=====================
+
+Apache SIS uses the `java.util.logging` framework with one minor difference:
+instead of invoking the `getLogger(String)` method provided by the `java.util.logging.Logger`
class,
+we rather invoke the method provided by the `apache.sis.util.logging.Logging` 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 `common-logging` is that
+SIS uses the standard Java API (except for the above-cited `getLogger` method) instead than
defining new API.
+
+
+
+Logger name    {#logger-name}
+-----------------------------
+
+The name given in argument to the `getLogger(String)` 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 (`org.apache.sis.internal.*`) 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.
+
+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 `LogRecord.getSourceClassName()`.
+
+
+
+Logging level    {#logging-level}
+---------------------------------
+
+All logging at `Level.INFO` or above shall be targeted to users or administrators, not to
developers.
+In particular `Level.SEVERE` 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).
+
+
+
+
 *[CRS]:  Coordinate Reference System
 *[JDBC]: Java DataBase Connectivity
 *[OGC]:  Open Geospatial Consortium

Modified: sis/site/trunk/content/contributor.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/contributor.mdtext?rev=1647622&r1=1647621&r2=1647622&view=diff
==============================================================================
--- sis/site/trunk/content/contributor.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/contributor.mdtext [UTF-8] Tue Dec 23 17:39:11 2014
@@ -144,6 +144,28 @@ to work on the SIS branch targeting the
     cd sis
     mvn install
 
+The [source code](source.html) page provides tips for opening the files in an IDE,
+and guidelines about the way SIS source code is organized.
+
+
+
+
+Committing changes    {#commit}
+===============================
+
+Copies or displacements of files shall be done with the `svn copy` or `svn move` command,
respectively.
+Be aware that not all IDE or graphical tools perform this action appropriately.
+*Always verify on the command-line*, at least the first times that a new tools is used, by
executing `svn status`.
+Files that have been moved or copied shall have a `A+` symbol in the left margin, like below:
+
+    :::text
+    D       my-directory/the-old-filename
+    A  +    my-directory/the-new-filename
+
+Using the proper SVN command is necessary for preserving the history, preserving the [SVN
properties](#svn-config),
+and consuming less space on the Apache server hosting the source code repository.
+
+
 
 
 Configuring Subversion properties    {#svn-config}
@@ -151,7 +173,7 @@ Configuring Subversion properties    {#s
 
 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:
 
@@ -160,10 +182,15 @@ Developers can specify default propertie
   * Scroll down to the `[auto-props]` section and make sure to assign the appropriate
     (usually `native`) value to the End Of Line (EOL) style of the files to be edited.
 
-Below is an example of a portion of Subversion configuration file:
+Below is an example of a portion of Subversion configuration file
+(real configuration files are typically larger):
 
     :::ini
     [miscellany]
+    # Whitespace-delimited globs which Subversion will ignore in its 'status' output.
+    global-ignores = *.class *.jar .* *~
+
+    # Enables automatic properties (defined below) for 'svn add' and 'svn import'.
     enable-auto-props = yes
 
     # Section for configuring automatic properties.

Modified: sis/site/trunk/content/source.mdtext
URL: http://svn.apache.org/viewvc/sis/site/trunk/content/source.mdtext?rev=1647622&r1=1647621&r2=1647622&view=diff
==============================================================================
--- sis/site/trunk/content/source.mdtext [UTF-8] (original)
+++ sis/site/trunk/content/source.mdtext [UTF-8] Tue Dec 23 17:39:11 2014
@@ -94,8 +94,24 @@ then execute the following steps:
 
 
 
-Classes naming convention    {#classes-naming}
-==============================================
+License header    {#license}
+============================
+
+All Java source files (`*.java`) shall begin with the current ASF license header as described
in [ASF Source Header][srcheaders].
+Properties source files (`*.properties`) used as inputs to some processor (e.g. the resource
compiler)
+shall have the same license header, but with lines prefixed by `#` instead of `*`.
+Properties files distributed as-is in the JAR files can summarize the license on a single
line for saving space,
+as below:
+
+    :::text
+    # Licensed to the Apache Software Foundation (ASF) under one or more contributor license
agreements.
+
+
+
+
+Naming convention    {#naming}
+==============================
+
 Implementations of GeoAPI interfaces usually (but not always) begin with `Abstract`, `Default`,
`Simple` or `General` prefixes.
 
   * The `Abstract` prefix is used when a class is abstract according ISO specifications —
it may or may not be be abstract in the Java sense.
@@ -129,6 +145,44 @@ a case-by-case basis. Of course, tabular
 
 
 
+Spaces and line length    {#spaces}
+-----------------------------------
+
+  * **Trailing Whitespaces:** Remove all trailing whitespaces.
+    + Eclipse users can use the _Source_ - _Cleanup_ option to accomplish this.
+    + NetBeans users can use the use the _Source_ - _Remove trailing spaces_ on a file-by-file
basis,
+      or set the _Preferences_ - _Editor_ - _On Save_ - _Remove trailing whitespaces_ option.
+  * **Indentation:** Use 4 space indents (except for XML files) and never use tabs.
+    + Use 2 space indents for XML files, because ISO/OGC XML schemas tend to have a very
deep structure.
+  * **Line wrapping:** 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.
+
+
+
+Declarations    {#declarations}
+-------------------------------
+
+Class, method and field declarations should use the keywords in the following order:
+
+  * `public`, `protected` or `private`
+  * `abstract` or `static`
+  * `final`
+  * `strictfp` (should be applied on all test classes)
+
+This is known as the "customary order" in the [Java Language Specification][JLS-order].
+
+
+
+
+Documentation formatting    {#javadoc}
+======================================
+
+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 `<table>` elements.
+
+
+
 Javadoc annotations    {#javadoc-tags}
 --------------------------------------
 
@@ -216,21 +270,6 @@ HTML tag                  | Description
 
 
 
-Miscellaneous    {#miscellaneous}
----------------------------------
-
-  * **License Header:** Always add the current ASF license header as described in [ASF Source
Header][srcheaders].
-  * **Trailing Whitespaces:** Remove all trailing whitespaces.
-    + Eclipse users can use the _Source_ - _Cleanup_ option to accomplish this.
-    + NetBeans users can use the use the _Source_ - _Remove trailing spaces_ on a file-by-file
basis,
-      or set the _Preferences_ - _Editor_ - _On Save_ - _Remove trailing whitespaces_ option.
-  * **Indentation:** Use 4 space indents (except for XML files) and never use tabs!
-    + Use 2 space indents for XML files, because ISO/OGC XML schemas tend to have a very
deep structure.
-  * **Line wrapping:** 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.
-
-
-
 *[ISO]: International Organization for Standardization
 *[OGC]: Open Geospatial Consortium
 
@@ -238,8 +277,7 @@ Miscellaneous    {#miscellaneous}
 [subversion]:       http://subversion.apache.org
 [git]:              http://git-scm.com
 [srcheaders]:       http://www.apache.org/legal/src-headers.html
-[standards]:        http://www.opengeospatial.org/standards
-[geoapi]:           http://www.geoapi.org/3.0/javadoc/index.html
+[JLS-order]:        http://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.1.1
 [mathml-wolfram]:   http://reference.wolfram.com/mathematica/XML/tutorial/MathML.html
 [mathml-dessci]:    http://www.dessci.com/en/reference/mathml/
 [mathml-fonts]:     http://developer.mozilla.org/en-US/docs/Mozilla/MathML_Project/Fonts



Mime
View raw message