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 2018/06/22 09:43:33 UTC

svn commit: r1031597 - in /websites/staging/sis/trunk/content: ./ branches.html index.html source.html

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">&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="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">&para;</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">&para;</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">&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="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">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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">&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 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">&para;</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">&para;</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">&para;</a></h2>
 <ul>
 <li><strong>Indentation:</strong> Use a consistent space indents and never use tabs.<ul>