Author: buildbot
Date: Fri Jun 22 09:43:33 2018
New Revision: 1031597
Log:
Staging update by buildbot for sis
Removed:
websites/staging/sis/trunk/content/branches.html
Modified:
websites/staging/sis/trunk/content/ (props changed)
websites/staging/sis/trunk/content/index.html
websites/staging/sis/trunk/content/source.html
Propchange: websites/staging/sis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Jun 22 09:43:33 2018
@@ -1 +1 @@
-1834085
+1834088
Modified: websites/staging/sis/trunk/content/index.html
==============================================================================
--- websites/staging/sis/trunk/content/index.html (original)
+++ websites/staging/sis/trunk/content/index.html Fri Jun 22 09:43:33 2018
@@ -153,9 +153,8 @@ However a command-line tool is provided
<p>Following links are for those who wish to contribute to Apache SIS:</p>
<ul>
<li><a href="contributor.html">New contributor</a>: background knowledge.</li>
-<li><a href="source.html">Source code</a>: fetching the code, opening in an
IDE, formatting.</li>
+<li><a href="source.html">Source code</a>: fetching the code, choosing a
branches, opening in an IDE, formatting.</li>
<li><a href="build.html">Build</a>: build from the source, create the PACK200
file.</li>
-<li><a href="branches.html">Branches</a>: master, geoapi-3.1, geoapi-4.0</li>
<li><a href="http://issues.apache.org/jira/browse/SIS";>Issue tracking</a>:
JIRA.</li>
<li><a href="release-management.html">Release management</a> (for release
managers)</li>
<li><a href="site-management.html">Web site management</a> (for release
managers and site maintainers)</li>
Modified: websites/staging/sis/trunk/content/source.html
==============================================================================
--- websites/staging/sis/trunk/content/source.html (original)
+++ websites/staging/sis/trunk/content/source.html Fri Jun 22 09:43:33 2018
@@ -100,24 +100,44 @@
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
<p>Apache SIS source code is maintained using <a
href="http://git-scm.com";>Git</a> version control.
For fetching the source code, use the following commands:</p>
-<div class="codehilite"><pre>git clone
https://gitbox.apache.org/repos/asf/sis.git
+<div class="codehilite"><pre>git clone https://gitbox.apache.org/repos/asf/sis
</pre></div>
<p>The above Git repository is mirrored on GitHub at <a
href="https://github.com/apache/sis";>https://github.com/apache/sis</a>.
-Note that the git repository does not include the non-free data (in particular
the <a href="epsg.html">EPSG geodetic dataset</a>).
+Note that the git repository does not include the non-free data, in particular
the <a href="epsg.html">EPSG geodetic dataset</a>.
Those data are currently provided only on Subversion repository.</p>
+<p>The source code repository contains <code>geoapi-3.1</code> and
<code>geoapi-4.0</code> branches in addition of <code>master</code>.
+The Apache SIS releases are created from the code on <code>master</code> only.
+However the actual development occurs on the <code>geoapi-4.0</code> branch
before to be merged to <code>master</code>.
+Those branches exist in order to experiment early new API and technologies â
since it may impact
+the library design â while keeping the releases compatible with officially
released environments.</p>
<p>The remaining of this page gives some guidelines about the way SIS source
code is organized.</p>
<div class="toc">
<ul>
+<li><a href="#development">Development branches</a><ul>
+<li><a href="#geoapi-4.0">GeoAPI 4.0 branch</a></li>
+<li><a href="#geoapi-3.1">GeoAPI 3.1 branch</a></li>
+<li><a href="#master">Master</a><ul>
+<li><a href="#differences">Code differences</a></li>
+<li><a href="#behavior">Behavioral differences</a></li>
+</ul>
+</li>
+</ul>
+</li>
<li><a href="#ide">Opening Apache SIS in an IDE</a><ul>
<li><a href="#netbeans">NetBeans</a></li>
<li><a href="#eclipse">Eclipse</a></li>
</ul>
</li>
<li><a href="#license">License header</a></li>
-<li><a href="#naming">Naming convention</a></li>
+<li><a href="#naming">Naming convention</a><ul>
+<li><a href="#internal">Internal packages</a></li>
+<li><a href="#substitutions">Substitution for non-existent classes</a></li>
+</ul>
+</li>
<li><a href="#formatting">Code formatting</a><ul>
+<li><a href="#imports">Import statements</a></li>
<li><a href="#spaces">Spaces and line length</a></li>
<li><a href="#brackets">Brackets</a></li>
<li><a href="#declarations">Member declarations</a></li>
@@ -136,9 +156,51 @@ Those data are currently provided only o
</li>
</ul>
</div>
+<h1 id="development">Development branches<a class="headerlink"
href="#development" title="Permanent link">¶</a></h1>
+<p>Users who want stability are encouraged to build from the
<code>master</code>.
+The master depends on GeoAPI 3.0.1,
+which is the <a href="http://www.geoapi.org/3.0/index.html";>latest GeoAPI</a>
released by the Open Geospatial Consortium (<abbr title="Open Geospatial
Consortium">OGC</abbr>).
+Developers who want to contribute to Apache SIS are encouraged to use the
<code>geoapi-4.0</code> branch for now.</p>
+<h2 id="geoapi-4.0">GeoAPI 4.0 branch<a class="headerlink" href="#geoapi-4.0"
title="Permanent link">¶</a></h2>
+<p>The <code>geoapi-4.0</code> branch is the recommended development branch
for now.
+This branch implements the interfaces defined in GeoAPI 4.0 snapshot
milestones.
+This branch uses new interfaces introduced in GeoAPI 4.0-SNAPSHOT and contains
upgrades for changes in existing GeoAPI interfaces.
+Some changes in GeoAPI 4.0-SNAPSHOT interfaces are incompatible with GeoAPI
3.0.1 interfaces.
+They are caused by changes in the underlying international standards, or by
evolution of Java technology.
+The content of this branch may be fully merged to <code>master</code> in the
future, depending on new GeoAPI releases from <abbr title="Open Geospatial
Consortium">OGC</abbr>.</p>
+<h2 id="geoapi-3.1">GeoAPI 3.1 branch<a class="headerlink" href="#geoapi-3.1"
title="Permanent link">¶</a></h2>
+<p>The <code>geoapi-3.1</code> branch implements the interfaces defined in <a
href="http://www.geoapi.org/snapshot/index.html";>GeoAPI 3.1 snapshot</a>
milestones.
+It has the same content that the <code>geoapi-4.0</code> branch, excluding
changes that are incompatible with GeoAPI 3.0.1.
+Developments happen on <code>geoapi-4.0</code> and are periodically merged to
<code>geoapi-3.1</code> with the necessary modifications.
+This branch is used merely as an intermediate step between the development
branch (<code>geoapi-4.0</code>) and <code>master</code>.
+Its content may be fully merged to <code>master</code> in the future, after
new GeoAPI releases from <abbr title="Open Geospatial
Consortium">OGC</abbr>.</p>
+<h2 id="master">Master<a class="headerlink" href="#master" title="Permanent
link">¶</a></h2>
+<p>The master is a merge of <code>geoapi-3.1</code> branch ported to the
interfaces defined by the <a href="http://www.geoapi.org/3.0/index.html";>GeoAPI
stable release</a>.
+This is the code which is built by the continuous integration system and
deployed on the Maven repository.
+<strong>Commits on master can not be removed, since <code>git push
--force</code> are not allowed on this branch.</strong>
+Commits should be pushed on above-cited development branch first,
+so they can be rearranged if needed before merge to <code>master</code>.</p>
+<h3 id="differences">Code differences<a class="headerlink" href="#differences"
title="Permanent link">¶</a></h3>
+<p>The main differences (apart version number) between <code>master</code> and
<code>geoapi-3.1/4.0</code> branches
+are the modifications necessary for implementing an older version of GeoAPI
interfaces.
+In particular, usages of non-released GeoAPI interfaces may be replaced
+by direct usages of the corresponding Apache SIS implementation classes.</p>
+<p>For security reasons and for avoiding misleading information, the following
functionalities are disabled on master for now
+(but are still enabled on branches as experimental features). In particular
the <code>Supervisor.ENABLED</code> flag controls
+whether the MBeans documented in the <code>org.apache.sis.console</code>
package are enabled or not.</p>
+<ul>
+<li>In
<code>core/sis-utility/src/main/java/org/apache/sis/internal/system/Supervisor.java</code>,
the <code>ENABLED</code> flag is set to <code>false</code>.</li>
+<li>In
<code>core/sis-utility/src/main/java/org/apache/sis/internal/util/TemporalUtilities.java</code>,
the <code>REPORT_MISSING_MODULE</code> flag is set to <code>false</code>.</li>
+</ul>
+<h3 id="behavior">Behavioral differences<a class="headerlink" href="#behavior"
title="Permanent link">¶</a></h3>
+<p>Because of changes between GeoAPI 3.0 and GeoAPI 4.0-SNAPSHOT, the
following aspects need special care:</p>
+<ul>
+<li>If <code>op</code> is an instance of <code>PassThroughOperation</code>,
then the <code>if (op instanceof SingleOperation)</code> expression
+ evaluates to <code>true</code> on master but to <code>false</code> on SIS
development branches.</li>
+</ul>
<h1 id="ide">Opening Apache SIS in an IDE<a class="headerlink" href="#ide"
title="Permanent link">¶</a></h1>
<p>Different SIS branches are available depending on the GeoAPI versions.
-The alternatives are listed in the <a href="branches.html">branches page</a>.
+The alternatives are listed in <a href="#development">above section</a>.
One thing to take in consideration can be summarized as below:</p>
<ul>
<li>There is no need to build GeoAPI prior working on SIS master.</li>
@@ -192,18 +254,48 @@ as below:</p>
<h1 id="naming">Naming convention<a class="headerlink" href="#naming"
title="Permanent link">¶</a></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>
+<p>Classes that do not implement an interface are usually not prefixed, even
if abstract.
+Classes implementing GeoAPI interfaces usually (but not always) begin with
<code>Abstract</code>, <code>Default</code>, <code>Simple</code> or
<code>General</code> prefix.</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>
<li>The <code>General</code> prefix is used when an implementation is designed
for use in the general case,
as opposed to other implementations specialized for a fixed number of
dimensions or other conditions.</li>
<li>Implementations specialized for a fixed number of dimensions are suffixed
with <code>1D</code>, <code>2D</code>, <code>3D</code> or <code>4D</code>
rather than being prefixed.</li>
</ul>
-<p>Classes that do not implement an interface are usually not prefixed, even
if abstract.</p>
+<p>Example: <code>GeneralEnvelope</code> class is an implementation of
<code>Envelope</code> interface for the multi-dimensional case.
+<code>Envelope2D</code> is another implementation of the same interface
specialized for the two-dimensional case.</p>
+<h2 id="internal">Internal packages<a class="headerlink" href="#internal"
title="Permanent link">¶</a></h2>
+<p>All classes in <code>org.apache.sis.internal</code> sub-packages are for
SIS usage only and may change without warning in any future release.
+Those classes are excluded from Javadoc and will not be exported by SIS Jigsaw
modules.
+Those packages may be renamed after SIS upgraded to JDK 9.</p>
+<h2 id="substitutions">Substitution for non-existent classes<a
class="headerlink" href="#substitutions" title="Permanent link">¶</a></h2>
+<p>When using a JDK 9 class that does not exist on JDK 8, define a class of
the same name in a
+<code>org.apache.sis.internal</code> sub-package with the minimal amount of
needed functionalities,
+provided that it can be done with reasonable effort.
+Otherwise just delete the JDK9-dependent code from the development branch.</p>
<h1 id="formatting">Code formatting<a class="headerlink" href="#formatting"
title="Permanent link">¶</a></h1>
<p>Apache SIS uses the standard Java conventions, except for the 80 characters
line length restriction.
The conventions listed below are guidelines. Some exceptions to those
conventions can occur but should
be rare (see <a href="#tabular-formatting">exceptions to coding
conventions</a>).</p>
+<p>For making merges between branches easier, refrain from doing massive code
reformatting unless:</p>
+<ul>
+<li>the modified files do not yet exist on the other branches;</li>
+<li>or the modified lines are known to be identical on all active branches
(merges work well in such cases);</li>
+<li>or the committer is willing to resolve the merge conflicts.</li>
+</ul>
+<h2 id="imports">Import statements<a class="headerlink" href="#imports"
title="Permanent link">¶</a></h2>
+<p>Isolate at the end of the imports section any import statements that are
specific to a platform.
+This separation allows any branch to re-arrange the common import statements
without generating
+conflicts with the platform-dependent import statements. Example:</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">java.io.File</span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">java.util.List</span><span
class="o">;</span>
+<span class="kn">import</span> <span
class="nn">org.opengis.metadata.Metadata</span><span class="o">;</span>
+
+<span class="c1">// Branch-specific imports</span>
+<span class="kn">import</span> <span
class="nn">org.opengis.feature.Feature</span><span class="o">;</span>
+</pre></div>
+
+
<h2 id="spaces">Spaces and line length<a class="headerlink" href="#spaces"
title="Permanent link">¶</a></h2>
<ul>
<li><strong>Indentation:</strong> Use a consistent space indents and never use
tabs.<ul>
