sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1031597 - in /websites/staging/sis/trunk/content: ./ branches.html index.html source.html
Date Fri, 22 Jun 2018 09:43:33 GMT
Author: buildbot
Date: Fri Jun 22 09:43:33 2018
New Revision: 1031597

Staging update by buildbot for sis

    websites/staging/sis/trunk/content/   (props changed)

Propchange: websites/staging/sis/trunk/content/
--- cms:source-revision (original)
+++ cms:source-revision Fri Jun 22 09:43:33 2018
@@ -1 +1 @@

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>
 <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
-<li><a href="branches.html">Branches</a>: master, geoapi-3.1, geoapi-4.0</li>
 <li><a href="">Issue tracking</a>:
 <li><a href="release-management.html">Release management</a> (for release
 <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="">Git</a>
version control.
 For fetching the source code, use the following commands:</p>
-<div class="codehilite"><pre>git clone
+<div class="codehilite"><pre>git clone
 <p>The above Git repository is mirrored on GitHub at <a href=""></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
 <p>The remaining of this page gives some guidelines about the way SIS source code is
 <div class="toc">
+<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>
 <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>
 <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>
 <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
+<h1 id="development">Development branches<a class="headerlink" href="#development"
title="Permanent link">&para;</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="">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
+<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
+<p>The <code>geoapi-3.1</code> branch implements the interfaces defined
in <a href="">GeoAPI 3.1 snapshot</a>
+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">&para;</a></h2>
+<p>The master is a merge of <code>geoapi-3.1</code> branch ported to the
interfaces defined by the <a href="">GeoAPI stable
+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
+<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>
+<li>In <code>core/sis-utility/src/main/java/org/apache/sis/internal/system/</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/</code>,
the <code>REPORT_MISSING_MODULE</code> flag is set to <code>false</code>.</li>
+<h3 id="behavior">Behavioral differences<a class="headerlink" href="#behavior" title="Permanent
+<p>Because of changes between GeoAPI 3.0 and GeoAPI 4.0-SNAPSHOT, the following aspects
need special care:</p>
+<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>
 <h1 id="ide">Opening Apache SIS in an IDE<a class="headerlink" href="#ide" title="Permanent
 <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>
 <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
-<p>Implementations of GeoAPI interfaces usually (but not always) begin with <code>Abstract</code>,
<code>Default</code>, <code>Simple</code> or <code>General</code>
+<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>
 <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
 <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>
-<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
+<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">&para;</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
+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
 <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
+<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>
+<h2 id="imports">Import statements<a class="headerlink" href="#imports" title="Permanent
+<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"></span><span class="o">;</span>
+<span class="kn">import</span> <span class="nn">java.util.List</span><span
+<span class="kn">import</span> <span class="nn">org.opengis.metadata.Metadata</span><span
+<span class="c1">// Branch-specific imports</span>
+<span class="kn">import</span> <span class="nn">org.opengis.feature.Feature</span><span
 <h2 id="spaces">Spaces and line length<a class="headerlink" href="#spaces" title="Permanent
 <li><strong>Indentation:</strong> Use a consistent space indents and never
use tabs.<ul>

View raw message